2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622 CATC Scripting Language 1.1 Reference Manual for the CATC BPT 1.0 Document Revision 1.
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.
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 . . . . . . . . . .
CATC SCRIPTING LANGUAGE 1.1 Reference Manual Table of Contents Compound Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 8 Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 9 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10 Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Call() . . . . . . . . . . . . . . . .
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.
CATC SCRIPTING LANGUAGE 1.
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.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 2 Reference Manual Values Escape Sequences These are the available escape sequences in CSL: Character Escape Sequence backslash Example Output \\ "This is a backslash: \\" This is a backslash: \ double quote \" "\"Quotes!\"" "Quotes!" horizontal tab \t "Before tab\tAfter tab" Before tab newline \n "This is how\nto get a newline." This is how to get a newline. single quote \' "\'Single quote\'" After tab 'Single quote' Table 2.
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 characters 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.
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.
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.
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.
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.
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.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 4 Reference Manual Operators Operator Symbol = += -= *= /= ^= %= |= Associativity >>= <<= &= Right to left Table 4.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 4 Reference Manual Operators Operator Operand Symbol Description Types Result Types Examples Index Operator [ ] Index or subscript Raw Bytes Integer Raw = '001122' Raw[1] = 0x11 List Any 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.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 4 Reference Manual Operators Operator Operand Symbol Description Types Result Types Examples Equality Operators == != Equal Not equal Integer-integer Integer 2 == 2 String-string Integer "three" == "three" Raw byte-raw byte Integer '001122' == '001122' List-list Integer [1, [2, 3]] == [1, [2, 3]] *Note: equality operations on values of different types will evaluate to false.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 5 Reference Manual Comments CHAPTER 5: COMMENTS 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 6 Reference Manual Keywords CHAPTER 6: KEYWORDS Keywords are reserved words that have special meanings within the language. They cannot be used as names for variables, constants or functions.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 7 Reference Manual Statements CHAPTER 7: STATEMENTS 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, ifelse statements, while statements, for statements, return statements, and compound statements. Expression Statements An expression statement describes a value, variable, or function.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 7 Reference Manual Statements 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).
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 7 Reference Manual Statements 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.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 7 Reference Manual Statements 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.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 7 Reference Manual Statements ... ; } 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 8 Reference Manual Preprocessing CHAPTER 8: PREPROCESSING 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 incorporated into a script. This way, commands can easily be located and reused. The syntax for %include is this: %include “includefile.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 9 Reference Manual Functions CHAPTER 9: FUNCTIONS 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.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 9 Reference Manual Functions 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.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 10 Reference Manual Primitives CHAPTER 10: PRIMITIVES Primitive functions are called similarly to regular functions, but they are implemented 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.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 10 Reference Manual Primitives 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 Format("0x%02X", 20); would yield the string 0x14.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 10 Reference Manual • Primitives • A space will insert a space before a positive signed integer. This only works with the conversion characters d and i. If both a space and a plus sign are used, the space flag 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 spaces.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 10 Reference Manual Primitives 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 () Parameter Meaning Default Value Comments bit_count integer Return value None.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 10 Reference Manual Primitives Resolve() Resolve( ) 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 ‘_’ (underscore) character since symbol names cannot contain spaces.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 11 Reference Manual BPT Primitives CHAPTER 11: BPT PRIMITIVES RunTest() RunTest( Address ) Parameter Meaning Address Bluetooth address of device to run test on Default Value Comments Return value • “Success” • Error message Comments This is the entry point into a script. When a script is run, the script's RunTest() function will be called. Include this command at the beginning of every script.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 11 Reference Manual BPT Primitives Comments Establishes an ACL connection with the specified device. Example result = Connect( Address ); if( result != "Success" ) { MessageBox( "Failed to connect!" ); } Disconnect() Disconnect( Address ) Parameter Meaning Address Bluetooth address of device to disconnect from Default Value Comments Return value • “Success” • “Failure” • “Disconnection in progress” Comments Closes the ACL connection with the specified device.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 11 Reference Manual BPT Primitives Inquiry() Inquiry( IAC, Timeout ) Parameter Meaning Default Value IAC Inquiry Access Code GIAC Timeout Timeout in units of 1.2 seconds Comments “GIAC”, or a 32-bit integer value Return value • Array of Bluetooth addresses that were found during the inquiry. • “Failure” • “Inquiry in progress” Comments Calling Inquiry() will block for the duration specified by Timeout.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 11 Reference Manual • • BPT Primitives “Failure” “Already connected” Comments Waits for an incoming ACL connection from a specified device for a specified time.
CATC SCRIPTING LANGUAGE 1.1 CHAPTER 11 Reference Manual BPT Primitives MessageBox() MessageBox( Message, Caption ) Parameter Meaning Message Text to display in the message box Caption Caption of the message box Default Value Comments “Script Message” Return value None. Comments Bring up a simple message box function with one “OK” button. This is a good way to pause execution of the script or indicate errors.
CATC SCRIPTING LANGUAGE 1.
