Transaction Script Language (TSL) Reference Manual

Transaction Script Language (TSL)
Reference Manual
TRANSACTION SCRIPT LANGUAGE (TSL)
REFERENCE MANUAL
Table Of Contents
1 Transaction Script Language
1.1 Introduction ............................................................................................. 1-1
2 Types, Operators and Expressions

2.1 Identifiers ................................................................................................ 2-1
2.2 Key Words............................................................................................... 2-1
2.3 Comments................................................................................................ 2-2
2.4 Data Types............................................................................................... 2-2
2.5 Variable Declaration ............................................................................... 2-2
2.6 Arrays ...................................................................................................... 2-3
2.6.1 Constant Array Declaration................................................................. 2-3
2.6.2 Format ................................................................................................. 2-4
2.6.3 Array Indexing .................................................................................... 2-4
2.7 Constant Declaration ............................................................................... 2-5
2.8 Arithmetic Operators............................................................................... 2-5
2.9 Relation and Logical Operators............................................................... 2-5
2.10 Type Conversion Operators .................................................................... 2-6
2.11 Compare .................................................................................................. 2-6
2.12 Assignment Operators and Expressions .................................................. 2-6
2.13 Special Parameters .................................................................................. 2-7
3 Function
3.1 Function Declaration ............................................................................... 3-1
3.2 Function Calls ......................................................................................... 3-2
3.3 Function Parameters ................................................................................ 3-3
3.4 Parameter and Return Value Size............................................................ 3-4
© 1996 - 2006 Teligent AB Id-008725 Rev A3
3.4.1 Parameter Size..................................................................................... 3-4

3.4.2 Return Value Size ............................................................................... 3-4
3.5 Local Transactions .................................................................................. 3-4
4 Transactions
4.1 trns Transaction Declaration ................................................................... 4-1
4.1.1 Transaction Type................................................................................. 4-1
4.1.2 Transaction Class ................................................................................ 4-1
Table Of Contents Transaction Script Language (TSL) Reference Manual

4.1.3 To Function ......................................................................................... 4-2
4.1.4 Return Function ................................................................................... 4-2
4.1.5 Send Data............................................................................................. 4-2
4.1.6 Response.............................................................................................. 4-2
4.1.7 Naming and Declaration...................................................................... 4-2
4.2 init Transaction Declaration .................................................................... 4-3
4.3 Artificial Transactions ............................................................................. 4-4
5 Statements
5.1 The if-else Statement ............................................................................... 5-1
5.2 The send Statement.................................................................................. 5-1
5.3 The wait Statement .................................................................................. 5-1
5.4 The while and break Statements .............................................................. 5-2
5.5 The debug, log, info and error Statements............................................... 5-2
5.6 The call Statement ................................................................................... 5-2
5.7 The return Statement................................................................................ 5-2
5.8 The format Statement .............................................................................. 5-2
5.9 The mwait Statement ............................................................................... 5-3
6 Script Program Structure

6.1 Compilation Units.................................................................................... 6-1
6.2 init Script ................................................................................................. 6-1
6.3 Work Flow ............................................................................................... 6-2
7 TSL Syntax
7.1 Syntax Specification ................................................................................ 7-1
8 SI System Calls
8.1 TIME ....................................................................................................... 8-2
8.1.1 Time Transactions ............................................................................... 8-2
8.1.2 Transaction for Get Time .................................................................... 8-3
8.1.3 Transactions for Date / Time Conversion ........................................... 8-4
8.1.4 Transactions for Current Time ............................................................ 8-5
8.2 WRITE..................................................................................................... 8-7
8.2.1 Write Transaction ................................................................................ 8-7
8.3 UTIL ........................................................................................................ 8-8

8.3.1 Function ‘DATABASE’ Transactions ................................................ 8-8
8.3.2 Function ‘READFILE’ Transaction .................................................. 8-10
8.3.3 Function ‘WRITEFILE’ Transaction ................................................ 8-11
8.3.4 Function ‘VOXFIDX’ Transaction ................................................... 8-12
8.4 RAND .................................................................................................... 8-14
8.4.1 RAND Transaction ............................................................................ 8-14

8.5 SNMP .................................................................................................... 8-15
8.5.1 SNMP Transaction ............................................................................ 8-15
8.6 ACUT .................................................................................................... 8-16
8.6.1 ACUT Transactions........................................................................... 8-16
9 AC Loaded Libraries
9.1 Overview.................................................................................................. 9-1
9.1.1 High Level Application, AC_ and Low Level Application Interaction 9-
1
9.2 Initialization............................................................................................. 9-2
9.3 Function Entry Points .............................................................................. 9-3
9.4 Termination ............................................................................................. 9-3
9.5 Transactions............................................................................................. 9-4
9.5.1 Initiate a New Instance (Session) ........................................................ 9-5
9.5.2 Execute a Function .............................................................................. 9-5
9.5.3 Terminate a Session............................................................................. 9-5
9.5.4 Obtain a List of Active Sessions ......................................................... 9-6

1-1
© 1996 - 2006 Teligent AB
1 TRANSACTION SCRIPT LANGUAGE
1.1 Introduction
This document is an overview of the Transaction Script Language.
The implementation of a service implies selecting data and functions from what is available
in the system, and combining those using decision logic to apply data modifications or
execute functions. This is defined as a Work Flow Application (WFA) in the Teligent system.
To be able to run a WFA the scripts will be processed by a Script Interpreter, SI.
A WFA is constructed from a set of scripts, written in the Transaction Script Language (TSL).
TSL is a programming language designed for writing programs / applications that can be
executed on the Teligent P90/E System. The features of the TSL are as follows:
• TSL is a high level language with instructions for sending transactions and performing
simple data manipulation.
• TSL is both a compiled and interpreted language. TSL code is compiled to TSL byte-
codes, which are then executed by the SI - a TSL runtime environment in the Teligent
P90/E System.
Chapter 1 Transaction Script Language

2-1
2 TYPES, OPERATORS AND EXPRESSIONS

Variables and constants are two of the basic data objects within a script. The difference
between a variable and a constant is
- a constant is given an initial value which it keeps during the execution of the script.
A constant declaration assigns name, type and value to an identifier.
- a variable does not need to be given an initial value and the value may be changed during
the execution of the script.
A variable declaration assigns name, type and optionally a value to an identifier.
Operators specify what to do with them and operators combined with variables and constants
make up expressions.
The type of an object specifies which values it can have and what operations can be performed
on it.
2.1 Identifiers
An identifier consists of alphabetical characters, numbers and the character underscore (_).
The first character must be alphabetic.
Identifiers are used as
• variable names
• constant names
• transaction names
• labels
2.2 Key Words

The following words are reserved as a part of the TSL and are called key words. They should
not be used for any kind of identifiers, including labels or transaction names.
Note: as TSL is case sensitive, the following words have to be written in lower case to
become a key word. Changing one or more letters in the word to upper case will prevent the
TSL compiler from recognizing it as a key word.
2phcm else inout proc td_clr
and end int response td_isset
break error integer retfunc td_rm
call fandf label return td_set
cc format log rsn tofunc
char if mod script trns
character in mwait send type
class indata or senddata wait
cmp info out SET_DEBUG_ON while
const init perform SET_DEBUG_OFF
debug init1 pifrt td_add
Chapter 2 Types, Operators and Expressions

2-2
2.3 Comments
A comment is identified by an exclamation mark (!) and is terminated by a new line.
Comments are recognized anywhere in a program, except inside a character string. All
characters are allowed in the comment.
2.4 Data Types

There are three basic data types in TSL:
• character
one single byte that can store one character.
• integer
one integer value. The maximum and minimum values are depending on the machine
(from -2147483648 to 2147483647 inclusive, on a 32 bit machine).
• td_set
the td_set variable can only be used within the special instructions which are used to
manipulate the set. These functions are td_add, td_clr, td_isset, td_rm and mwait. The
.size parameter for a td_set variable is the number of transaction identifiers currently in
the set.
2.5 Variable Declaration

Variables can be declared as integers, characters, character arrays or a set of transaction
identifiers.
Example:
integer x1;
character y1;
character y2 [10];
td_set t;
In this example, x1 is an integer, y1 is a character, y2 is a character array and t is a set of
transaction identifiers.
Note that declaring a character is identical to declaring a character array with the size one.
Example:
character y;
y[0] =: 'a';
In this example, a character variable y is declared, which is identical to an array of size
one. This is then used with an index, which is legal for an array of size one.
When a variable is first declared, it has no value (unless it is initialised). A variable with no
value cannot be used on the right-hand of an assignment. Once a variable has been assigned
a value, either by being on the left-hand side of an assignment or by being in response of a
received transaction, it can be used on the right-hand side of an assignment.

2-3
A variable that has no value is said to be ‘idle’. A variable is idle when it is first declared,
unless it has an initial value. A variable can become idle when it is in the response of a
transaction and the transaction is sent. If the FICS field associated with a variable in a
transaction response is missing, then the variable will change state to not idle after the
transaction returns and the variable will be set to either 0 or '\000' depending of variable type.
More examples:
Initialize length to 42
integer length 42;
Initialize the character char_name to ‘A’
character char_name 'A';
Allocate a 100 character long string and set it to ‘TEST’. Note the variable will be NULL-
terminated and test1.size = 5.
character test1[100] "TEST";
Allocate a 100 character long string and set it to 'TEST'. Note the variable will not be NULL-
terminated and test2.size = 4.
character test2[100] 'TEST';
Variables may not be initialized by another variable, only by numbers (integer) and strings
(character).
integer height;
character test3[100];
The height and test3 are idle, i.e. the value can be any value. It does not have to be a zero.
2.6 Arrays
2.6.1 Constant Array Declaration
A character array is defined in two ways - either within double quotes (”) or single quotes
('). Character strings within double quotes are NULL terminated while strings within single
quotes are not NULL terminated.
The character backslash (\) is treated as in C-style, i.e. if the following character is a lower
case letter of one of the following - a, b, f, n, r, t or v - it is a C escape sequence, such as \n
for newline. The backslash also allows octal and hex characters in the form \123 and \x3f.
Otherwise backslash quotes the following character, so that the following character or string
matches without the backslash. For example the string \hello will be treated as hello, and
the string “\“hello” \” will be treated as “hello”.
The length of a string is given by .size. The .maxsize operator gives the maximum size. The
maximum length of a character string is 2048 bytes.
Example:
character greeting[100] "Hello";

2-4
2.6.2 Format
The keyword format is used to assign a formatted string to a character buffer. The format
string is composed of characters and zero or more variable expansion specifications, i.e.
ordinary character (not $) is copied unchanged to the character buffer and each variable
expansion results in a replacement of the variable value.
Each variable replacement starts with a $ and is followed by the variable to replace.
An integer variable will be converted into a signed decimal notation.
In a character array variable will all the characters from the array be written to the output
character array variable.
A td_set variable will be converted to a comma separated list of transaction number included
in the set with the status represented by the letters "O" (outstanding) and "R" (received)
appended to each number.
Examples:
int x;
character message[100];
format message =: "Value of x is $x";
if x has the value 10 the character array message will contain the value [Value of x is 10\0].
Note the trailing \0 character.
character name[10];
format message =: 'Name of x is $name';
if name has the value Mr Smith, the character array message will contain the value [Name
of x is Mr Smith].
td_set t;
format message =: 'Transaction status $t';
if t contains transaction identifier 1,2 and 3 and the transaction number 2 has returned, the
character array message will contain the value [Transaction status 1O,2R,3O].
2.6.3 Array Indexing

Reference to array elements are made through indexing into the array. To facilitate this, the
elements of the array are numbered starting at zero. Hence an array declared with n elements
is indexed using indices between 0 and n-1.
In TSL it is possible to index an array with one or several, maximum n-1, elements. An
indexing with only one element is of the following form
identifier[ expression ]
where expression is an expression that evaluates to a positive integer defining the index.
An indexing with more than one element is of the following form
identifier[ expression1 .. expression 2]

2-5
where expression1 and expression2 are expressions that evaluates to a positive integer
defining the start index and the end index. The second index must be larger or equal than
the start index.
2.7 Constant Declaration

All constants must be declared before the are used. A constant is declared in the same way
as a variable but have the keyword “const” as a prefix in the declaration.
Example:
const integer maxint 2147483647
2.8 Arithmetic Operators

The arithmetic operators in the TSL are as follows:
* multiplication
+ plus
- minus
/ integer division, as 5/2 equals 2
mod modulus
The multiplication, integer division and modulus operators have the same precedence,
which is higher than plus and minus. The arithmetic operators associate from left to right.
Use parenthesis to avoid conflicts.
2.9 Relation and Logical Operators

The relation operators are
< less than, as 1 < 2 equals 1.
> greater than, as 1 > 2 equals 0.
They have the same precedence but it is lower then the arithmetic ones.
After them in precedence are the equality operators
= equality, compare equality
<> not equal
There are two logical operators in the TSL

and logical and
or logical or
The precedence of these two operators is below the relation operators. By definition the
numeric value of an relation or logical expression is 1 if the relation is true and 0 if it is false.
As in C, all values that are not 0 are logical true.

2-6
2.10 Type Conversion Operators

To be able to convert between characters and integers there are two type converters:
int converts an ASCII string into an integer. The first character in the string not being a
number terminates the conversion, i.e. converting "213abc" will give the value 213.
char converts an integer into an ASCII string.
Note: Type conversion from character to integer may cause a runtime error if the
character buffer contains non digits.
2.11 Compare
The only relation operator for characters in TSL is cmp. The cmp instruction compares
byte strings;
buf1 cmp buf2
If the string buf1 is identical to the string buf2 the result is one (1), otherwise the result is
zero (0).
Example:
"ONE" cmp "ONE" equals 1
"ONE" cmp "TWO" equals 0
"abc" cmp "abc" equals 1
"abc" cmp ´abc´ equals 0 (the first operand is NULL terminated, and the second is
not)
2.12 Assignment Operators and Expressions

The assignment operator in TSL is "=:". The assignment operator stores a value in the
object designed by the left operand. The left operand must be a modifiable variable. The
two operands must be of the same type.

2-7
2.13 Special Parameters

Parameters like “variable-name.size” and “transaction-name.TPTFmember” are specifically
treated in the TSL. These parameters can only be referred to - assignment to them is not
allowed.
• variable-name.size gives the size of the variable on the format integer.
• variable-name.maxsize gives the number of bytes allocated for the variable (an integer
value).
• transaction-name.TPTFmember gives the specification as below;
TPTFmembers: Description: Format:

issuestamp Time, in epoch, when the transaction integer
was sent
compstamp Time when the component integer
returned the transaction
eye Identifier character, 4 bytes
version Version character, 4 byte
tptftype Transaction type character, 4 byte
cc Completion code integer
rsn Reason code integer
prio Priority integer
class Transaction class integer
transnumb Transaction number integer
tofunc.component Destination component character, 4 byte
tofunc.function Requested function character, 4 byte
retfunc.component Returning component character, 4 byte
retfunc.function Returning function character, 4 byte
flags Flags integer
comptransnumb AC internal transaction number integer
datalen Data length integer
Example:
If the transaction has the name "make_call" the parameter
"make_call.version" gives the version of the TPTF (transaction format).

3-1
3 FUNCTION
3.1 Function Declaration

A function can be declared anywhere a variable can be declared, except inside another
function. This rule is similar to the one for declaring functions in the C-language.
A function can return an integer, a character array or a set of transaction identifiers. If the
function returns a character array, it can be of varying size. The function can take arguments;
each argument can be an integer, a character array or a character (remembering that a character
is equivalent to a character array of size one).
Each parameter in a function definition is preceded by one of the keywords ‘in’, ‘out’ or
‘inout’.
Parameters marked ‘in’ must not be marked idle (i.e. they must be initialised) in a function
call. They will have the same value after the function call as before it.
Parameters marked ‘inout’ must not be marked idle in a function call. They may be changed
in value or marked idle after the function call.
Parameters marked ‘out’ may be idle when the function is called. Then they may have a
value or may still be idle after the function call.
Refer to paragraph 3.3 for more information.
An example of a function declaration in TSL is as follows:
integer func1( in integer x, out integer y )
{
y =: 1;
return x + y;
}
It is also possible to declare a function with no return value, as follows:
proc logfunc( in character a )
{
log "parameter a is a";
}
This example logs a string passed as a parameter.
Chapter 3 Function
3-2
3.2 Function Calls

A function can be called in one of two ways, using the return value or ignoring the return value.
If assuming the following fragment of code:
integer a;
integer b;
integer c;
a =: 1;
b =: 2;
Then an example of a call ignoring the return value is as follows:
call func1( in a, out b );
An example of a call using the return value is as follows:
call c =: func1( in a, out b );
Note that, unlike the C-language, a function call cannot be part of a more complex expression.
Also note the use of the “in” and “out” keywords in the function call. These must match the
function declaration. A call parameter using the “in” keyword can be either a variable or an
expression. A call parameter using the “out” or “inout” keyword must be a variable.
A function body can contain variable declarations, transaction declarations and executable
code. These function as usual in TSL. The parameters are also used as normal, except that
if a parameter is a character array, it is still declared as a character. For example, in the
following declaration:
character func2( inout character p1 )
{
if ( p1.size = 1 )
p1 =: 'X';
else
p1 =: "This is an array of characters";
return "More Text";
}
If the function is called with a single character as a parameter, it is set to the value ‘X’. If
the function is called with a character array with size greater than one as a parameter, it is
set to the value; ‘This is an array of characters’.
In both cases the function returns a value that is a character array.
This could be used as follows:
character x[50];
character y;
y =: 'a';
x =: "hello world";
x =: call func2( inout y );
y =: call func2( inout x );
Chapter 3 Function
3-3
In the first call to func2, y has the value ‘a’. Inside the function this is changed to ‘x’ and
since this is an ‘inout’ parameter, the value of y is updated when the function returns. Also
the function returns the value ‘More Text’, which is copied into x.
In the second call to func2, x has the value ‘More Text’. Inside the function this is changed
to ‘This is an array of characters’, and since this is an ‘inout’ parameter, the value of x is
updated when the function returns. Also the function returns the value ‘More Text’, the first
character of which is copied into y. A runtime warning is produced since the data assigned
to y in this case is truncated.
3.3 Function Parameters

Function parameters must be marked with one of the keywords ‘in’, ‘out’ or ‘inout’. These
keywords must be used both in the function declaration and in the function call.
A parameter with the ‘in’ keyword must be initialised before the function is called and the
value is made available inside the function.
When a parameter is marked as ‘in’, the function can be called with a variable or an expression
in that position. Any changes to the value made in the function are not kept when the function
returns. If the variable used in calling the function is idle (i.e. has no value), a runtime error
occurs when the call is made.
A parameter with the ‘out’ keyword does not need to be initialised when the function is
called. The value of the parameter is not made available inside the function. Any changes
to the value made inside the function are kept when the function returns.
When a parameter is marked as ‘out’, the function can only be called with a variable in that
position. The initial value of the parameter is ignored or the parameter can be idle (i.e. has
no value). The parameter is marked as idle inside the function. If the parameter in the function
is idle when the function returns, then the parameter passed in the call is idle. If the parameter
is not idle, then the value is assigned to the parameter passed in the call.
A parameter with the ‘inout’ keyword must be initialised when the function is called, and
the value is made available inside the function. Any changes to the value are kept when the
function returns.
When a parameter is marked as ‘inout’, the function can only be called with a variable in
that position. If the variable used in calling the function is idle (i.e. has no value), a runtime
error occurs. If the parameter in the function is idle when the function returns, then the
parameter passed in the call is marked as idle. If the parameter in the function is not idle,
then the value is assigned to the parameter passed in the call.
Chapter 3 Function
3-4
3.4 Parameter and Return Value Size

3.4.1 Parameter Size
When a function is declared with a character parameter, the declaration does not specify the
size of the parameter. The function call can pass a parameter of any desired size and the
function will work on the called value.
The ‘.maxsize’ operator may be used inside the function to discover the size of the character
parameter passed. The ‘.size’ operator can be used to discover the size of the value currently
stored in the parameter.
The size of integer parameters is fixed.
The size of td_set variable are the number of identifiers added to the set.
3.4.2 Return Value Size

When a function is declared to return a character value, the function can return a value of
any desired size from a single character to a large character array or string value. If the
returned value is to be assigned to a variable, the caller must make sure the variable is large
enough to take the returned value.
The size of integer return values is fixed.
The size of a td_set variable are the number of identifiers added to the set.
3.5 Local Transactions

Local transactions can be declared inside a function. The ‘senddata’ and the ‘response’ can
include variables local to the function and global to the script. They can also include
parameters.
If a transaction has a response, it is an error to send a local transaction in a function and then
return from the function before the response has been received.
A transaction declared inside a function cannot be accessed except from within the function.
Chapter 3 Function
4-1
4 TRANSACTIONS
Transactions are used for passing data between components or scripts. In TSL the response
from a transaction is used to assign a value to a variable. There are two ways a variable is
assigned a value from a transaction; either from the response of an outgoing transaction from
the script, or from the data field in the init transaction to a script.
For a complete description of the transactions for each component, refer
to the Component’s Reference Manual.
There are two types of transaction declarations in TSL: init and trns. The init declaration
is what the script receives at the start of the execution and the trns is declaration of transactions
sent from the script.
4.1 trns Transaction Declaration

The outgoing transaction declaration consists of objects defined in the transaction and naming
the transaction. The objects that can be defined in a transaction are as follows;
transaction type (tptftype)
transaction class
destination component (tofunc.component)
requested function (tofunc.function)
returned component (retfunc.component)
returned function (retfunc.function)
indata
responsedata
4.1.1 Transaction Type

The transaction type must be declared in the transaction. The transaction type must be one
of the types defined in the Teligent P90/E Transaction Format, TPTF. The transaction type
consists of four characters, where the forth character is a space.
4.1.2 Transaction Class

The classes that can be declared is 2phcm (two phase commit), fandf (fire and forget) and
pifrt (route to platform interface). The class field in the transaction declaration is optional.
To set more than one class, the classes have to be separated by comma.
If the class pifrt is defined the routing information has to be added in the FICS SESSIONID.
The value of this FICS is the link ID and the routing component (8 characters long)
Example:
0001XSRA
For more information of these classes, refer to the Teligent P90/E Kernel Reference Manual.
Chapter 4 Transactions
4-2
4.1.3 To Function
The requested function and the destination component for the transaction must be declared
in the field tofunc, four characters each.
Example:
tofunc:comp,func;
4.1.4 Return Function

If the response of the transaction is to be send to another component the function and the
receiving component must be declared in the field retfunc, four characters each.
Example:
retfunc:comp,func;
4.1.5 Send Data

The data (variables) to be sent with the transaction are declared in the field senddata. The
senddata field consists of a list of variables and the FICS names. Each variable is separated
by a comma ( ,).
The maximum length of the FICS name is 10 characters.
Example:
senddata:var1=FICSNAME1,var2=FICSNAME2;
4.1.6 Response
The data (variables) that are in the response from the transaction are declared in the field
response. The response field consists of a list of variables and the offset in the response
data-buffer or a list of variables and the FICS names. Each variable is separated by a comma
( ,).
Example:
response:var1=ANUMBER,var2=BNUMBER;
4.1.7 Naming and Declaration

Each transaction is assigned a name to be used by the interpreter. The naming of the
transaction follows the same rules as naming variables.
The maximum length of the transaction name is 44 characters.
Example:
The syntax of the transaction declaration
trns name{
type:"CUP ";
tofunc:"SI7_","CNUM";
retfunc:;
senddata:var1=FICSNAME1,var2=FICSNAME2;
response:var3=FICSNAME3;
}
4-3
4.2 init Transaction Declaration

The fields in the init declaration are cc, rsn, response and indata. The first three fields are
only defined in the init script. These fields specify what to send back after execution of an
application. Default value for the cc and rsn is zero (0). The indata fields specifies the
incoming parameters to a script.
The syntax of the init declaration in an init script is as follows:
init
{
cc: cc_value;
rsn: rsn_value;
indata: parameter = "FICSNAME";
response: parameter = "FICSNAME";
}
cc_value and rsn_value are of the format integer. If these fields are empty the default value
0 (zero) is used.
4-4
4.3 Artificial Transactions

Refer to Teligent P90/E Kernel Reference Manual for a description of how to declare an
artificial transaction. The artificial transaction must be described both in the artificial
transaction description and the transaction set description.
Below follows an example of an artificial transaction. The example shows the artificial
transaction described in three different ways, the first two shows how the transaction can
be described in the TM_ configuration and the third shows how the transaction can be
described in a script.
The artificial name of the transaction, in this example LOADERXX, is divided in two parts
in the tofunc field: the first four characters, LOAD, for the ‘comp’ and the last four characters,
ERXX, for the ‘func’.
Artificial transaction description
[LOADERXX]
CUP AC_A DELT 0x0112 100 0
CUP AC_A LOAD 0x0112 100 0
Transaction set description
ART LOAD ERXX 0x0112 100 0
Script
trns load_trns
{
type:"ART ";
cc:;
rsn:;
tofunc: "LOAD", "ERXX";
retfunc:;
senddata:;
CONST_APPL = "APPL",
version = "VERSION",
execname = "EXECNAME",
path = "PATH"
response:;
}
5-1
5 STATEMENTS
The Script Interpreter of TSL uses if-else logic to evaluate the different instructions in the
script. The statements that the Script Interpreter can evaluate besides ‘if’ are ‘send’, ‘wait’,
‘while’, ‘break’, ‘mwait’, ‘error’, ‘info’, ‘debug’, ‘log’, ‘format’, ‘call’, ‘return’ and ‘td
manipulation’.
5.1 The if-else Statement

The if statement is used for conditional execution of commands. There may optionally be
an ‘else’ following. The conditional statements are enclosed in braces, i.e. { and }.
The condition tested by the “if” construction must be a single variable, declared in the
declaration part of the script.
The syntax of the ‘if-else’ statement in TSL:
if a > b
{
send transaction1;
wait transaction1;
}
else
{
send transaction2;
}
The first transaction is sent if the variable fits the boolean expression, i.e. if ‘a > b’ is true.
If the boolean expression ‘a > b’ is false, the second transaction is sent if it is an else part.
5.2 The send Statement

The send statement sends a transaction and waits for acknowledgement that the transaction
has been sent.
5.3 The wait Statement

The wait statement is used for waiting for the response from a transaction that has been sent
from the Script Interpreter.
Chapter 5 Statements
5-2
5.4 The while and break Statements

The while statement is used for loops. The loop evaluates a test expression and continues
until the test is false. If the while loop should be completed before the test is false, use the
break statement, and the loop is stopped immediately.
The syntax of the ‘while’ statement in TSL:
while a > b
{
send transaction1;
wait transaction1;
}
If the boolean expression ‘a > b’ is true, the statements are executed. The loop continues
until the boolean expression is false.
5.5 The debug, log, info and error Statements

The debug, log, info and error statements are used for generating log messages, which will
be distributed by syslogd (operating system logger).
The difference between the log functions are the level of the message. The level determine
the importance of the message. The levels are, in order of decreasing importance
error [LOG_ERROR]
info [LOG_INFO]
log, debug [LOG_DEBUG]
The use of SET_DEBUG_ON and SET_DEBUG_OFF are deprecated and are only available
for backward compatibility. They were used for turning on and off log messages.
5.6 The call Statement

Refer to chapter 3 for information on the call statement.
5.7 The return Statement

Refer to chapter 3 for information on the return statement.
5.8 The format Statement

Refer to paragraph 2.6 for information the format statement.
5-3
5.9 The mwait Statement

The mwait (multiple wait) statement waits for a number of transactions to return. The
argument to mwait is a set of transaction identifier. The set is manipulated with four
statements described below. The transaction identifier is returned from the updated send
statement which return a unique transaction id.
• td_clr (transaction descriptor set):
Clear the set.
• td_add (transaction descriptor set, transaction id):
Add a given transaction identifier to the set
• td_rm (transaction descriptor set, transaction identifier):
Remove a given descriptor from the set
• td_isset (transaction descriptor, transaction descriptor set):
Test to see if a transaction is outstanding or have returned.
The mwait statement returns the number of transactions that are not outstanding contained
in the transaction set.
Note: The values of the variables associated with the reply of a transaction are set when
the transaction returns regardless of whether the script is waiting for them or not.
Example:
trans t1{...}
trans t2{...}
trans t3{...}
integer a;
integer b;
integer c;
integer n;
td_set td;
a, send t1;
b, send t2;
c, send t3;
td_clr(td);
td_add (td, a);
td_add (td, b);
td_add (td, c);
n, mwait td;
if td_isset (td, a)
{
}
if td_isset (td, b)
{
}
if td_isset (td, c)
{
}
6-1
6 SCRIPT PROGRAM STRUCTURE

This chapter is a briefing of the higher levels of program structure for TSL programs. The
two levels of organization described in this chapter are compilation units and applications.
A compilation unit contains the source code for one or more scripts. An application is a
collection of one or several related compilation units.
6.1 Compilation Units

A compilation unit is a set of scripts, which are the highest level syntactic structure that TSL
recognizes. The structure of a script is as follows:
The script starts with the reserved words 'script' and the script name enclosed in double
quotes. The maximum length of the script name is eight (8) characters. The script ends with
the reserved words 'end script' and the script name.
Example:
script "script name"
.
.
end script "script name"
In the first part of the script, the definition part, all variables, transactions and labels are
declared. In the second part, the executable part, the flow control is defined specifying in
which order to send transactions and evaluate expressions.
6.2 init Script

All compilation units must have one init script declared. It is this script that receives control
when a compilation unit is started. The init script contains two features that differ from the
other scripts. These features are:
# The special init transaction declaration that defines what to send back in the response.
This transaction identifier can be accessed with the name init1.
* All identifiers declared in the init script is global and can be accessed from all other
scripts in the compilation unit.
Chapter 6 Script Program Structure

6-2
6.3 Work Flow

The Work Flow in a compilation unit describes in which order the script is interpreted. The
init script is the script that is interpreted at the start of a compilation unit execution. To switch
script, a transaction is sent. The syntax of this transaction is as follows:
trns identifier
{
type:;
tofunc:"nextscript","";
retfunc:;
senddata:;
response:;
}
‘nextscript’ defines which script to interpret.
All fields in the transaction declaration except the tofunc field and the senddata field should
be blank. The data in the senddata field is optional.
After sending the transaction, the SI switches script and start interpreting the new script.
The whole script is switched including the local data area. Reaching the end of the script is
the same as reaching the end of the compilation unit, i.e. the script does not return to the
‘sending’ script.
Chapter 6 Script Program Structure

7-1
7 TSL SYNTAX
7.1 Syntax Specification

The postfix " * " means zero or more, and the postfix " + " means one or more.
APPLICATION := SCRIPTS+
SCRIPTS := “script” <script name>

DECLARATIONS+
INSTRUCTIONS*
“end script” <script name>
DECLARATIONS := VARIABLE_DECLARATION*
CONSTANT_DECLARATION*
INIT_TRANSACTION_DECLARATION
TRANSACTION_DECLARATION*
FUNCTION_DECLARATION*
VARIABLE_DECLARATIONS := “integer” VARIABLE_NAME “;”

| “character” VARIABLE_NAME “;”
| “character” VARIABLE_NAME“ [“ NUMERIC_VALUE “]” “;”
| “integer” VARIABLE_NAME NUMERIC_VALUE”;”
| “character” VARIABLE_NAME “
[“NUMERIC_VALUE “]” STRING_LITERAL”;”
| “character” VARIABLE_NAME “[“ NUMERIC_VALUE “]”
NULL_TERMINATED_STRING_LITERAL”;”
| “td_set” VARIABLE_NAME “;”
VARIABLE_NAME := <the name of the variable>
NUMERIC_VALUE := <a number>
CONSTANT_DECLARATION := “const” “integer” CONSTANT_NAME

NUMERIC_VALUE “;”
| “const” “character” CONSTANT_NAME
NULL_TERMINATED_ STRING_LITERAL “;”
| “const” “character” CONSTANT_NAME STRING_LITERAL “;”
Chapter 7 TSL Syntax

7-2
CONSTANT_NAME := <the name of the constant>
NULL_TERMINATED_STRING_LITERAL := <string inclosed in double quotas>

STRING_LITERAL := <string inclosed in single quotas>
INIT_TRANSACTION_DECLARATION := “init” “{“ “indata” “:” FICS_ARRAY “;” “}”
FICS_ARRAY =: <a comma separated list of FICS ended with semicolon “;”>
FICS := VARIABLE_NAME “=” NUMERIC_VALUE

| VARIABLE_NAME “=” CONSTANT_STRING
| VARIABLE_NAME “=” CONSTANT_NAME
TRANSACTION_DECLARATION := “trns” TRANSACTION_NAME “{“

TRANSACTION_TYPE
TRANSACTION_CLASS
COMPLETION_CODE
REASON_CODE
TO_FUNCTION
RETURN_FUNCTION
INPUT_FICS
RESPONSE_FICS “}”
TRANSACTION_NAME =: <the name of the transaction>
TRANSACTION_TYPE := “type” “:” “;”

| “type” “:” VARIABLE_NAME “;”
| “type” “:” NULL_TERMINATED_STRING_LITERAL “;”
TRANSACTION_CLASS := “class” “:” CLASS_VALUES “;”
|CLASS_VALUES := CLASS_VALUES “,” CLASS_VALUE
| CLASS_VALUE
|CLASS_VALUE := “2phcm”
| “fandf”
| “pifrt”
COMPLETION_CODE := “cc” “:” CODE_PAIRS “;”
REASON_CODE := “rsn” “:” CODE_PAIRS “;”

7-3
CODE_PAIRS := “;”
| CODE_PAIR “;”
CODE_PAIR := “(“ NUMERIC_VALUE “-” NUMERIC_VALUE “)” SCRIPT_NAME

| “(“ NUMERIC_VALUE “)” SCRIPT_NAME
SCRIPT_NAME := VARIABLE_NAME
| NULL_TERMINATED_STRING_LITERAL
TO_FUNCTION := “tofunc” “:” COMPONENT “,” FUNCTION “;”
RETURN_FUNCTION := “retfunc” “:” COMPONENT “,” FUNCTION “;”
COMPONENT := VARIABLE_NAME
FUNCTION := VARIABLE_NAME
INPUT_FICS := “senddata” “:” FICS_ARRAY “;”
RESPONSE_FICS := “response” “:” FICS_ARRAY “;”
FUNCTION_DECLARATION := “integer” FUNCTION_NAME

“(“ VARIABLE_LIST “)” FUNCTION_BODY
| “character” FUNCTION_NAME “(“ VARIABLE_LIST “)”
FUNCTION_BODY
| “td_set” FUNCTION_NAME “(“ VARIABLE_LIST “)”
FUNCTION_BODY
| “proc” FUNCTION_NAME “(“ VARIABLE_LIST “)”
FUNCTION_BODY
VARIABLE_LIST := VARIABLE_LIST “,” VARIABLE

| VARIABLE
VARIABLE := VARIABLE_TYPE “integer” VARIABLE_NAME

| VARIABLE_TYPE “character” VARIABLE_NAME
| VARIABLE_TYPE “td_set” VARIABLE_NAME

7-4
VARIABLE_TYPE =: “IN”
| “OUT”
| “INOUT”
FUNCTION_BODY =: DECLARATIONS+
INSTRUCTIONS*
FUNCTION_CALL := “CALL” FUNCTION_NAME “(“ PARAMETER_LIST “)” “;”

| “CALL” VARIABLE_NAME “=” FUNCTION_NAME
“(“ PARAMETER_LIST “)” “;”
PARAMETER_LIST := PARAMETER_LIST “,” PARAMETER

| PARAMETER
PARAMETER := “IN” EXPRESSION

| “OUT” VARIABLE_NAME
| “INOUT” VARIABLE_NAME
ASSIGNMENT := L_VALUE “=:” EXPRESSION “;”
L_VALUE := VARIABLE_NAME
| VARIABLE_NAME “[“ EXPRESSION “]”
| VARIABLE_NAME “[“ EXPRESSION “..” EXPRESSION “]”
EXPRESSION := VALUE
| VALUE BINARY_OPERATOR VALUE
VALUE := L_VALUE
| STRING_LITERAL
| NUMERIC_VALUE
| BRACKETED_EXPRESSION
| UNARY_OPERATOR VALUE
BRACKETED_EXPRESSION := “(“ EXPRESSION “)”

7-5
BINARY_OPERATOR := “+”
| “-””
| “*”
| “/”
| “mod”
| “cmp”
| “=”
| “<>”
| “<“
| “>”
| “and”
| “or”
UNARY_OPERATOR := STRING_TO_NUMBER_OPERATOR
| NUMBER_TO_STRING_OPERATOR
STRING_TO_NUMBER_OPERATOR := “int”
NUMBER_TO_STRING_OPERATOR := “char”
INSTRUCTIONS := CONDITIONAL
| SEND
| WAIT
| MWAIT
| TD_ADD
| TD_RM
| TD_CLR
| ASSIGNMENT
| DEBUG
| BREAK
| LOG
| FUNCTION_CALL
| FORMAT
| RETURN
CONDITIONAL := “if” TEST “{“ INSTRUCTIONS “}”

| “if” TEST “{“ INSTRUCTIONS “}” “else”
“{“ INSTRUCTIONS “}”
| “while” TEST “{“ “INSTRUCTIONS “}”

7-6
TEST := EXPRESSION
| “td_isset” “(“ VARIABLE_NAME” “,” VARIABLE_NAME “)” “;”
SEND := “send” TRANSACTION_NAME “;”

| VARIABLE_NAME “,” “send” TRANSACTION_NAME “;”
WAIT := “wait” TRANSACTION_NAME “;”
MWAIT := VARIABLE_NAME “,” “mwait” VARIABLE_NAME “;”
TD_ADD := “td_add” “(“ VARIABLE_NAME “,” VARIABLE_NAME “)” “;”
TD_RM := “td_rm” “(“ VARIABLE_NAME “,” VARIABLE_NAME “)” “;”
TD_CLR := “td_clr” “(“ VARIABLE_NAME “)” “;”
DEBUG := “SET_DEBUG_ON”
| “SET_DEBUG_OFF”
LOG := “error” STRING_LITERAL “;”

| “info” STRING_LITERAL “;”
| “log” STRING_LITERAL “;”
| “debug” STRING_LITERAL “;”
FORMAT := “format” VARIABLE_NAME “=” LITERAL_STRING “;”

| “format” VARIABLE_NAME “=” NULL_TERMINATED_LITERAL_STRING “;”
BREAK := “break”
RETURN := “return”
| “return EXPRESSION”

8-1
8 SI SYSTEM CALLS
The Script Intepreter, SI, supports some library functions that are accessible from the scripts.
The functions supported are TIME, WRITE, UTIL, RAND, SNMP and ACUT, each
described in this chapter.
The interface to these functions is a transaction with the type field not set and the component
in the tofunc field set to one of the supported library functions, e.g. ‘TIME’. Below is an
example of a transaction that will access the TIME function.
trns time
{
type:;
tofunc:"TIME","";
retfunc:;
senddata:
timefunc="TIMEFUNC";
response:
;
}
These transactions are processed locally in the SI and therefore no transaction number,
issuestamp or timestamp is set in the transaction. The only tptf member that is updated is
the cc and reason codes.
Note that scripts cannot be named like these functions, since the functions are accessed in
the same way as a local script.
Chapter 8 SI System Calls

8-2
8.1 TIME
Three different times that represent the same time exist on a Teligent P90/E system.
• Universal Coordinated Time (UTC)
The computer's hardware clock must be set to this time. It is normally set and updated
automatically from a time server.
• The installed time zone for the operating system
This is the time displayed by the operating system when using the command ‘date’. This
is normally set during installation of the operating system.
• P90 system time
The time zone for all Teligent P90/E components, configured in tm.cfg and in the daemon
configuration files (e.g. tpd, dmm and a2s).
Time can be read in tsl applications as well as directly in the Unix environment. The time
is changed during daylight saving time (summer / winter time). The time zone (TZ) variable
defines the time change. This is set in the configuration files; tm.cfg.
Different time in time zones can be calculated using own time zone variables, if the scripts
have to present a time in a specified time zone. The time is presented correct for the zone
as well as daylight saving time during summer.
Note:
• Timestamp should be used for all calculations. Time should not be used
with time zone as it will cause problems at time change during summer
/ winter change.
• Timestamp should be used for all storage of time and date in database.
• Time functions with time zone variable should be used when presenta-
tion of time is made.
8.1.1 Time Transactions

The time calls supported are get time, current time operation and time conversion. All time
function calls are on the local host where the SI is executed.
All calls to the time function require the FICS TIMEFUNC. This FICS specifies which
function to use. The functions may also require / return the following FICS:
TIMEZONE Time zone in format std offset [dst [offset][ , rule]].
If TIMEZONE is empty, the P90sysTZ time zone
(cfg_p90sysTZ) is used. For more information about TIME-
ZONE variable, see Unix man page; man tzset.
DATE Date without time specification in ISO format;
CCYY-MM-DD
Date without time specification (TZ);
±HHMM [TZN]

8-3
TIME Time without date specification in ISO format;

HH:MM:SS
Time without date specification (TZ);
HH:MM:SS ±HHMM [TZN]
DATETIME Date and time in ISO format;
CCYY-MM-DD HH:MM:SS
Date and time (TZ);
CCYY-MM-DD HH:MM:SS ±HHMM [TZN]
TIMESTAMP Date and time in epoch (time in seconds since January 1, 1970).
For dates only, the timestamp is given for 00:00:00 the requested
date.
For time values (without date reference), the number of seconds
from midnight (00:00:00) is given.
The different values for TIMEFUNC and the other FICS arguments required / returned for
each transaction are described in paragraph 8.1.2 - 8.1.3.
The new time transaction for daylight saving and timezones are described below as well as
the ‘old’ time function.
Explanation of abbreviations in the transaction description:
TZ = Time Zone variable. Example: WTE-1 WTES-2, M3.5.0/2, M10.5.0/3
TZN = Time Zone Name (CET, EST, etc.)
UTC = Universal Coordinated Time
8.1.2 Transaction for Get Time
Corresponding Function New Function

Note: this is the ‘old’ TSL time function calls. ‘Local
time’ is the installed timezone in the operating
system.
None Get current timezone argument:

TIMEFUNC = GLTZ
FICS Arguments:
None
Return FICS:
TIMEZONE

8-4
8.1.3 Transactions for Date / Time Conversion

system.
ISO date and time to epoch: Convert datetime to timestamp calculated

TIMEFUNC = XDTE from TZ:
FICS Arguments: TIMEFUNC = YDTE
DATETIME FICS Arguments:
Return FICS: TIMEZONE
TIMESTAMP DATETIME
Note: Field ±HHMM [TZN) is ignored
Return FICS:
TIMESTAMP
ISO date to epoch: Convert date to timestamp calculated
TIMEFUNC = XD2E from TZ:
FICS Arguments: TIMEFUNC = YD2E
DATE FICS Arguments:
TIMESTAMP DATE
Note: Field ±HHMM [TZN) is ignored
Return FICS:
TIMESTAMP
ISO time to epoch: Compatible, use the ‘old’ function.
TIMEFUNC = XT2E
FICS Arguments:
TIME
Return FICS:
TIMESTAMP
Epoch to ISO date and time: Convert timestamp to datetime formatted
TIMEFUNC = XDTI by TZ:
FICS Arguments: TIMEFUNC = YDTE
TIMESTAMP FICS Arguments:
DATETIME TIMESTAMP
Return FICS:
DATETIME

8-5
8.1.4 Transactions for Current Time

system.
Local date and time in ISO: Current date/time formatted by TZ:

TIMEFUNC = LDTI TIMEFUNC = SDTI
FICS Arguments: FICS Arguments:
None TIMEZONE
Return FICS: Return FICS:
DATETIME DATETIME
UTC date and time in ISO: Compatible, use the ‘old’ function
TIMEFUNC = CDTI
FICS Arguments:
None
Return FICS:
DATETIME
Local date in ISO: Current date formatted by TZ:
TIMEFUNC = LDAI TIMEFUNC = SDAI
None TIMEZONE
DATE DATE
UTC Date in ISO: Compatible, use the ‘old’ function

TIMEFUNC = CDAI
FICS Arguments:
None
Return FICS:
DATE
Local time in ISO: Current time formatted by TZ:
TIMEFUNC = LTII TIMEFUNC = STII
None TIMEZONE
TIME TIME
UTC time in ISO: Compatible, use the ‘old’ function
TIMEFUNC = CTII
FICS Arguments:
None
Return FICS:
TIME

8-6

system.
Local date and time in epoch: Current timestamp, date and time calcu-
TIMEFUNC = LDTE lated by TZ:
FICS Arguments: TIMEFUNC = SDTE
None FICS Arguments:
TIMESTAMP Return FICS:
TIMESTAMP
Current timestamp, UTC date and time Compatible, use the ‘old’ function
in epoch:
TIMEFUNC = CDTE
FICS Arguments:
None
Return FICS:
TIMESTAMP
Local date in epoch: Current timestamp, date calculated by
TIMEFUNC = LDAE TZ:
FICS Arguments: TIMEFUNC = SDAE
TIMESTAMP
Current timestamp, UTC date in epoch: Compatible, use the ‘old’ function
TIMEFUNC = CDAE
FICS Arguments:
None
Return FICS:
TIMESTAMP
Local time in epoch: Current timestamp, time calculated by
TIMEFUNC = LTIE TZ:
FICS Arguments: TIMEFUNC = STIE
TIMESTAMP
Current timestamp, UTC date in epoch: Compatible, use the ‘old’ function
TIMEFUNC = CDAE
FICS Arguments:
None
Return FICS:
TIMESTAMP

8-7
8.2 WRITE
Note: This function is not used in Teligent P90/E version 1.6 and later.
The UTIL function type WRITEFILE described in paragraph 8.3.3 should be
used instead.
This function is used to write data to a file on the node where the SI is executed.
Example:
trns write_file
{
type:;
tofunc:"WRITE","";
retfunc:;
senddata:
"/tmp/file.txt" = "PATH"
"Hello World" = "BUF"
"5" = "SIZE"
"whatever" = "APPEND"
"whatever" = "NEWLINE"
response:;
}
In this example the transaction appends ‘Hello’, i.e. the first five characters in BUF, to the
file /tmp/file.txt. A newline is added in the file after ‘Hello’.
8.2.1 Write Transaction

The FICS arguments for a write transaction are the following. Note that PATH and BUF are
mandatory.
PATH The name of the file to write (full path)
BUF The data to be written
SIZE The number of bytes to write. If SIZE is not supplied the com-
plete buffer will be written.
APPEND If given a value (the value does not matter) the text in BUF will
be appended to the file. If the APPEND FICS is not sent the file
will be truncated and the text in BUF will be written first in the
file.
NEWLINE If given a value (the value does not matter) a newline '\n' will be
written to the file after the text in BUF.

8-8
8.3 UTIL
The UTIL function contains four different function types; DATABASE, READFILE,
WRITEFILE and VOXFIDX. The function types requires a FICS ‘UTILTYPE’, which
specifies the function to use.
8.3.1 Function ‘DATABASE’ Transactions

This function creates and handles a local database on the node where the SI is executed. The
database table structure are
primkey,data1,data2,...,datan
Entries in the same table are not required to contain the same number of data fields.
The function requires the FICS FUNC. This FICS specifies which database operation to use.
The functions may also require / return the following FICS:
TABLE The name of the table
PRIMKEY The name of the primkey
DATAn Primkey data
VERIFY This is used when updating an entry in the database. If the data in
this FICS is exactly the same as in the entry it will be updated.
The following reason codes are common for all functions:

1 Missing TABLE FICS
2 Missing PRIMKEY FICS
4 Cannot open database
5 Cannot open database
6 IO error
7 Primkey not in table
8 Subkey DATAn not found in table
11 Verify data and database data mismatch
Transaction example for the DATABASE function:
trns insert_bike
{
type:;
tofunc:"UTIL","";
retfunc:;
senddata:
"DATABASE" = "UTILTYPE",
"INSERT" = "FUNC",
"BIKES" = "TABLE",
"MC" = "PRIMKEY",
"HARLEY DAVIDSSON" = "DATA1",
"BLACK" = "DATA2";
response:;
}
8-9
Create a database: Remove database:

FUNC = CREATE FUNC = RM_TABLE
TABLE TABLE
None None
Insert an entry to database (This function Write an entry to database (This func-
will not overwrite the entry if it already tion will overwrite the entry if it already
exists): exists):
FUNC = INSERT FUNC = WRITE
TABLE TABLE
PRIMKEY PRIMKEY
DATA1 DATA1
. .
DATAn DATAn
None None
Get next entry in database: Get previous entry in database:
FUNC = GETN FUNC = GETP
TABLE TABLE
PRIMKEY PRIMKEY
PRIMKEY PRIMKEY
Read an entry in database: Delete an entry from database:
FUNC = READ FUNC = DELETE
TABLE TABLE
PRIMKEY PRIMKEY
DATA1 None
.
DATAn
Update an entry in the database (This
function will update an entry in the data-
base only if the data in VERIFY is exactly
the same as in the entry. If not, the DATAn
FICS will be updated with the current
value):
FUNC = VERIFY_UPDATE
FICS Arguments:
TABLE
PRIMKEY
DATAn
VERIFY
Return FICS:
DATAn
8-10
8.3.2 Function ‘READFILE’ Transaction

This function reads a string from a text file on the node where the SI is executing.
The file is pointed out by the FICS FILE from the position indicator FILEPOS into the buffer
pointed out by READDATA. One line is read. If the line is longer than 254 characters, only
the first 254 characters will be returned in the READDATA and the FICS NEWFILEPOS
will give the position of the 255th character. Reading stops after an EOF or a newline. The
newline is not stored in the buffer. A '\0' is stored after the last character in the buffer.
The function requires the following FICS values:
FILE Full path to the file to read from.
FILEPOS Position in file to start reading from.
Return FICS:
READDATA The text that was read from the file at the requested position.
NEWFILEPOS The first position after the read text in the file (i.e. where the
reading was stopped).
The following reason codes are possible:

1 Missing FICS field.
2 Error reading file.
Transaction example for the READFILE function:
character new_pos[32];
character buf[256];
trns AC_read_file
{
type:;
tofunc:"UTIL","";
retfunc:;
senddata:
"READFILE" = "UTILTYPE",
"etc/motd" = "FILE",
"0" = "FILEPOS",
response:
new_pos = "NEWFILEPOS",
buf = "READDATA";
}

8-11
8.3.3 Function ‘WRITEFILE’ Transaction

This function writes a string or a data buffer to a file on the node where the SI is executing.
Transaction example for the WRITEFILE function:
The transaction below writes ‘Hello’ to the file /tmp/file.txt.
trns write_file
{
type:;
tofunc:"UTIL","";
retfunc:;
senddata:
"WRITEFILE" = "UTILTYPE",
"/tmp/fil.txt" = "FILE",
"Hello World" = "BUF",
"5" = "SIZE",
"1" = "APPEND";
response:;
}
The function requires the following FICS values:
PATH The name of the file to write to (full path). This FICS is compul-
sory.
BUF The data to be written. This is compulsory.
SIZE The number of bytes to write. If SIZE is not supplied the com-
plete buffer will be written.
APPEND If set to any value but 0 (zero), the text given in BUF will be
appended to the file. If set to 0 (zero) or if APPEND is not sup-
plied, the file will be truncated and the text given in BUF will be
written first in the file.
The following reason codes are possible:

0 OK
1 Missing FICS field.
2 Could not open file.
3. Could not write to file.
4 Invalid value in FICS SIZE.

8-12
8.3.4 Function ‘VOXFIDX’ Transaction

This function reads a file with characters, e.g. numbers, and corresponding index in a voice
file. It then builds a long string with the characters index value. This can for example be
used to convert telephone numbers to index in a voice file with digits.
The index files are handled in five different ways depending on the index file type:
time This type is used to substitute a time hh:mm to an index string.
The index file should start with the following two lines:
uktime
[hh:mm]
date This type is used to substitute a date mm:dd to an index string.
The index file should start with the following two lines:
ukdate
[mm:dd]
number This type is used to substitute a number series, e.g. phone
number, to an index string. The index file should start with the
following two lines:
number
[n]
count This type is used to substitute a number to an index string. The
index file should start with the following two lines:
count
[n]
uindex This type is used to be able to store text messages and to retrieve
the message un-processed from an index file. This type can, for
instance, be used to store / access messages in different lan-
guages. This index file will start with the following two lines:
string
[s]
Information stored in index files is stripped out from any white space delimeter when being
accessed (" ", "\t" and "\n").
The type "string" will skip the character stripping. String message may have the ";" character
in its text, provided it was stored in the form "\;" (in order to distinguish it from the end of
the index delimeter).
The FICS arguments for this function are
VOXFILE The name of file with index definitions
DATA1 The data which will generate index string.
Return FICS:
VOXIDX The index string
IDXLEN The length of the index string

8-13
Transaction example for the VOXFIDX function:

trns voxfidx
{
type:;
tofunc:"UTIL","";
retfunc:;
senddata:
"VOXFIDX" = "UTILTYPE",
"/var/p90/number.idx" = "VOXFILE",
"123" = "DATA1";
response:
index = "VOXIDX",
indexlen = "IDXLEN";
}
If the voxfile /var/p90/idx/number.idx contains the following info
number
[n]
[0] "0,8000;
[1] "8000,8000;
[2] "16000,8000;
[3] "24000,8000;
the index variable will contain the following data "8000,8000;16000,8000;24000,8000"
after the transaction has returned.

8-14
8.4 RAND
This function will generate a random number returned in the FICS DATA in the range 0 to
the range specified in the FICS RANGE.
Example:
integer range;
integer random;
trns rand
{
type:;
tofunc:"RAND","";
retfunc:;
senddata:
range = "RANGE";
response:
random = "DATA";
}
8.4.1 RAND Transaction

The FICS arguments for this functions is
RANGE An integer >0. This number will be the upper limit for the
returned generated number.
Return FICS:
DATA The generated random number in the range 0 to range <specified
in the input FICS RANGE>.

8-15
8.5 SNMP
the SNMP function will send a TPTF-transaction from the SI to the a2s daemon. The a2s
daemon will translate the TPTF transaction into an SNMP trap and set instruction.
8.5.1 SNMP Transaction

The FICS arguments for this functions is
_SNMP_ALMACT Valid values are
A = Raise (when fault occur)
C = Clear (when fault has been fixed)
R = Reset (when P90/E operator reset alarm)
N = Notify (repetition of alarm)
TPTFHEAD TPTF struct packed in a 64 bytes character buffer.
_ALMTYPE Valid values are
F = Functional alarm
S = Supervision alarm
R = Resource alarm
A = Application alarm
_NODENAME Node name. Literal string, maximum length 256.
_THREAD Name of the system thread (for supervision alarms). Default is
TM_. Literal string, maximum length 256.
RESOURCE Name of the component (for transaction alarms). Default is
‘UNKNOWN’. Literal string, maximum length 256.
ERRORNUM Unique number of this alarm (may be 0 (zero) if no number is
assigned). Integer, default is 0.
_SEVERITY Severity of fault.
ERRORTXT Textual description of this fault. Literal string, maximum length
256.
ALARMTXT Textual description of this fault. Literal string, maximum length
256.
TIME Timestamp of the alarm. Integer
RSRCMGR The Teligent P90/E component suffering/detecting the fault. Lit-
eral string, maximum length 256.
TRSNUM Transaction number for the alarm.

8-16
8.6 ACUT
ACUT is the library interface to local database files within the AC_ and ALH that executes
the script.
8.6.1 ACUT Transactions

The function requires the FICS ‘FUNC’. The function requires the FICS ‘FUNC’. This FICS
specifies which database operation to use. The functions may also require / return the
following FICS:
TABLE The name of the table, max length 256 characters.
PRIMKEY The name of the primkey.
DATAn Primkey data. The data associated with the key is specified in
one or more FICS, where n is an integer starting from 1.
LOCKKEY Lock key is used to prevent other from opening the table. For-
mat: Integer.
LOCKTYPE The lock type can either be exclusive or shared. If the lock type
is exclusive no other can lock the table. If the lock type is shared
several can lock the table with the same lock key. Integer; 1
(exclusive), 2 (shared)
VERIFY This is used when updating an entry in the database. If the data in
this FICS is exactly the same as in the entry it will be updated.
TABLENAME List of all open tables.
The following reason codes are common for all functions:

1 Missing TABLE FICS
2 Missing PRIMKEY FICS
3 Missing or unknown FUNC FICS
4 Cannot lock database
5 No such database
6 Database read/write error
7 Primkey not in database
8 Primkey already exist in database
9 Subkey not in database
10 Missing SUBKEY FICS
11 Verify data and database data mismatch
12 Error in handling list of databases
13 Missing LOCKTYPE FICS
14 Missing LOCKKEY FICS
15 Cannot add FICS to transaction

8-17
Example:
trns opendb
{
type:;
tofunc:"ACUT",""
retfunc:;
senddata:
"INSERT"= "FUNC",
"dbname"= "TABLE",
"primkey"= "PRIMKEY",
"data1"= "DATA1";
response:
}
Create a table: Open a table:

FUNC = CREATE FUNC = OPEN
TABLE TABLE
[LOCKKEY] [LOCKKEY]
None None
List all open tables: Close all open tables:
FUNC = LISTTABLE FUNC = CLOSEALL
None None
TABLENAME None
Close a table: Read a key from the database:
FUNC = CLOSE FUNC = READ
TABLE TABLE
Return FICS: PRIMKEY
None Return FICS:
DATAn
Lock the table: Unlock the table:
FUNC = LOCK FUNC = LOCK
TABLE TABLE
LOCKTYPE LOCKKEY
LOCKKEY Return FICS:
Return FICS: None
None

8-18
Create a key and write data to the key. Write data to the key in the database.
(The default behaviour of the insert rou- (The default behaviour of the write rou-
tines is to fail if the key already exists in tines is to enter new key/data pair,
the table): replace any previously existing key):
FUNC = INSERT FUNC = WRITE
TABLE TABLE
PRIMKEY PRIMKEY
[DATAn] [DATAn]
DATAn DATAn
Get next entry in database. If the key is Get previous entry in database. If the key
not set the first key will be returned: is not set the last key will be returned:
FUNC = GETN FUNC = GETP
TABLE TABLE
[PRIMKEY] [PRIMKEY]
PRIMKEY PRIMKEY
Delete an entry from database: Delete the table. This will remove the
FUNC = DELETE table and its underlaying files from the
FICS Arguments: disk:
TABLE FUNC = RMTABLE
PRIMKEY FICS Arguments:
Return FICS: TABLE
None Return FICS:
None
Update an entry in the database (This Unload the table. The table and its
function will update an entry in the data- underlaying files are still on the disk and
base only if the data in VERIFY FICS is can be reloaded later:
exactly the same as in the entry. If not, FUNC = UNLOAD_TABLE
the DATAn FICS will be updated with FICS Arguments:
the current value): TABLE
FUNC = VERIFY_UPDATE Return FICS:
FICS Arguments: None
TABLE
PRIMKEY
VERIFY
[DATAn]
Return FICS:
DATAn

9-1
9 AC LOADED LIBRARIES
9.1 Overview
The purpose of the AC loaded library is to provide the application programmer with a set
of run time libraries or functions to use in applications. In effect it enables the Teligent P90/
E with a set of DLL's that a product can use in real-time. These libraries (written in TSL)
will provide all the low level and complex functionality needed. The application programmer
can then concentrate on building the application at a higher level of abstraction. Furthermore
it will provide a mechanism to rapidly port complex products such as UM to Application
Builder or any similar environment.
The high level application is the actual call flow and the low level application (or DLL-
application) provides the core functions of the service.
The concept behind AC Loaded Libraries is to:
1. Provide rapid porting of current products to Application Builder.
2. To give the Teligent P90/E and its products an extensive set of run time libraries that
can be accessed by another application.
3. To protect the application programmer from having to perform complex tasks in
Application Builder, i.e. these tasks exist in the loaded libraries, not the controlling
application).
4. To provide better resource management.
5. To provide better control of the state of an application within the platform.
6. Functions in the loaded library may become modules that can easily be built into
Application Builder.
9.1.1 High Level Application, AC_ and Low Level Application

Interaction
The diagram below shows an overview of the interaction between the controlling high level
application, the AC_ and the low level (loaded library) application.
High Level (Si) AC_ Low Level (Si)
The high level Interfaces the The low level

application high level application is the
(or controlling application with loaded library
application) the low level and contains
contains the application. the low level
actual call flow. modules and/or
Transactions functions.
sent between
the two are
internal AC_
transactions.
Fig. 9.1 AC_ loaded libraries overview
Chapter 9 AC Loaded Libraries

9-2
The high level application (or controlling application) contains the actual ‘call flow’. This
may be written in Application Builder.
The low level application is the loaded library and contains the low level modules and/or
functions. Only one low level application may be owned by each high level application. The
low level application is usually written in TSL.
The AC_ is the interface between the high level and the low level application. It will forward
requests from the high level application to the correct instance of a low level application.
Transactions passed between the two are AC_ internal transactions. The low level application
and the corresponding high level application will be on the same AC_.
Note that the low level application and the corresponding high level application(s) must be
on the same AC_ component. A definition file should be used to load the low level
application(s) upon AC_ startup.
To use the resources of a low level application instance the following transaction flow must
occur in the high level application:
1. TPTFTYPE = LIB / TOFUNC = INIT
Initialise a low level application instance (session)
2. TPTFTYPE = LIB / TOFUNC = Four (4) character function name
Execute a single function
3. TPTFTYPE = LIB / TOFUNC = TERM
Terminate the low level instance when the high level application ends.
9.2 Initialization
As the controlling application starts it will submit one or more initialization transactions
back to the owning AC_ (with tptf type = LIB and tofunc = INIT). These transactions are
‘internal’ AC_ transactions. Upon receipt of the INIT transaction the AC_ will start the
particular low level application on one of its free Si’s. The low level application and the
associated session will exist until either terminated by the high level application or until the
low level application has terminated.
When the low level application has been initialized it will need to decrement the allocatable
counter by 1. It is necessary to place a limit on only one (1) low level application per
controlling script.

9-3
9.3 Function Entry Points

Normally an application will have an ‘init’ sub-script and one or more other sub-scripts that
perform certain tasks. The Si will execute the ‘init’ script and then the flow control of the
application is such that unless a sub-script is called the application will terminate when there
are no further sub-scripts for the application to call.
Within the AC loaded library the following will occur:
As the low level application is initialized all sub-scripts are read and the ‘init’ part of the
application is executed as normal. This allows the application to initialize any variables.
When the init script has completed the AC_ will keep the Si active and the application ready
to await any further function calls from the controlling application.
The controlling high level application will call any functions of the low level application by
sending an internal AC_ transaction with the tptf type set to ‘LIB’ and the tofunc set to the
name of the function (application sub-script) to execute. Any application FICS data can be
passed if required.
The AC_ will route this internal transaction to the correct Si that is running the low level
application. This Si will change flow of control to the correct sub-script. When the sub-script
has finished its execution it will return any FICS data or reason codes back to the controlling
high level application, and the calling transaction is returned.
It will be necessary to disallow local variables within a particular sub-script. In addition to
this it is suggested that the instance of the main script init transaction needs to be used as
the mechanism to return transactions from. Otherwise the sub-script init transaction needs
to be saved into global data. If this mechanism is chosen, then it will not be possible to have
local variables in the sub-scripts.
Note that all variables must remain in an active and initialized state in the low level
application. This will allow the low level application to retain an internal state of the high
level application.
9.4 Termination
When a high level application terminates the low level application associated with that will
also be terminated.
However, control of the low level application can be passed from high level application to
high level application (or Si to Si). This is achieved by the application emitting an AC_
EXEC transaction with the tptf type set to LIB. The AC_ will internally transfer ownership
of the low level application to the new instance of the high level application. This behaviour
is not permitted with an AC_ REXC transaction.
The low level application can if desired be terminated by the high level application by sending
an internal TERM transaction, with the tptf type set to LIB.
Refer to paragraph 9.5 for more information of the transactions.

9-4
9.5 Transactions
The following FICS is required/returned:
EXECNAME The name of the script to execute when the BEGN transaction is
sent.
Format: alpha numeric
VERSION The version of the script to execute.
Format: alphanumeric
APPL The application ID of the script to execute.
SESSION Identifies a single instance of a low level application. This will
be sued by the high level application when sending all transac-
tions to that instance.
Format: numeric (integer)
SESSLIST Returns a comma delimited list of all sessions active.
LIFESPAN Returns information of how long a specified session has been
active.
Format: numeric (seconds)
The following reason codes are common for all functions described in this paragraph except
for STTS:
0 OK
1 The application does not exist
2 AC_ out of resources
4 The application exists
5 Input data is missing in the transaction
6 Wrong path or the path does not contain the script

9-5
9.5.1 Initiate a New Instance (Session)

This transaction initiates a new instance (session) of a low level application.
Transaction type = LIB
tofunc = INIT
The function requires the following FICS:
EXECNAME
VERSION
APPL
+ other application applicable FICS.
The following FICS is returned:
SESSION
9.5.2 Execute a Function

This transaction executes a function in an initiated low level application.
tofunc = Four (4) character function name
SESSION
+ application FICS.
The following FICS are returned:
SESSION
+ application FICS
9.5.3 Terminate a Session

This transaction terminates a session.
tofunc = TERM
SESSION
The following FICS is returned:
SESSION

9-6
9.5.4 Obtain a List of Active Sessions

This is an external transaction. It can be used to obtain a list of active sessions. This is useful
for resource management. The SESSION FICS is optional. If omitted, all active sessions on
the specific AC_ are returned. Otherwise the transaction will return the time a session has
been active.
Transaction type = CRD
Destination component = AC_?
tofunc = STTS
[SESSION]
The following FICS are returned:
SESSLIST
or
LIFESPAN
Reason code:
10 Invalid session

Transaction Script Language (TSL) Reference Manual

Uploaded by

Copyright:

Available Formats

Transaction Script Language (TSL) Reference Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Transaction Script Language (TSL) Reference Manual

Uploaded by

Copyright:

Available Formats

Transaction Script Language (TSL)

2 Types, Operators and Expressions

3.4.1 Parameter Size..................................................................................... 3-4

Table Of Contents Transaction Script Language (TSL) Reference Manual

6 Script Program Structure

8.3 UTIL ........................................................................................................ 8-8

Table Of Contents Transaction Script Language (TSL) Reference Manual

Table Of Contents Transaction Script Language (TSL) Reference Manual

1 TRANSACTION SCRIPT LANGUAGE

Chapter 1 Transaction Script Language

2 TYPES, OPERATORS AND EXPRESSIONS

2.2 Key Words

Chapter 2 Types, Operators and Expressions

2.4 Data Types

2.5 Variable Declaration

Chapter 2 Types, Operators and Expressions

Chapter 2 Types, Operators and Expressions

2.6.3 Array Indexing

Chapter 2 Types, Operators and Expressions

2.7 Constant Declaration

2.8 Arithmetic Operators

2.9 Relation and Logical Operators

There are two logical operators in the TSL

Chapter 2 Types, Operators and Expressions

2.10 Type Conversion Operators

2.12 Assignment Operators and Expressions

Chapter 2 Types, Operators and Expressions

2.13 Special Parameters

TPTFmembers: Description: Format:

Chapter 2 Types, Operators and Expressions

3.1 Function Declaration

3.2 Function Calls

3.3 Function Parameters

3.4 Parameter and Return Value Size

3.4.2 Return Value Size

3.5 Local Transactions

4.1 trns Transaction Declaration

4.1.1 Transaction Type

4.1.2 Transaction Class

4.1.4 Return Function

4.1.5 Send Data

4.1.7 Naming and Declaration

4.2 init Transaction Declaration

4.3 Artificial Transactions

5.1 The if-else Statement

5.2 The send Statement

5.3 The wait Statement

5.4 The while and break Statements

5.5 The debug, log, info and error Statements

5.6 The call Statement

5.7 The return Statement

5.8 The format Statement

5.9 The mwait Statement

6 SCRIPT PROGRAM STRUCTURE

6.1 Compilation Units

6.2 init Script

Chapter 6 Script Program Structure

6.3 Work Flow

Chapter 6 Script Program Structure