3Using Siebel eScript

Using Siebel eScript

This chapter describes how to use Siebel eScript. It includes the following topics:

• Using Operators in Siebel eScript

• Coding with Siebel eScript

• Guidelines for Using Siebel eScript

Using Operators in Siebel eScript

This topic describes operators you can use in Siebel eScript. It includes the following topics:

• Overview of Mathematical Operators

• Using a Shortcut Operation to Do an Arithmetic Operation

• Modifying the Sequence That Siebel eScript Uses to Evaluate an Expression

• Using Logical Operators and Conditional Expressions

• Increasing or Decreasing the Value of a Variable

• Using Less Code to Write an Else Statement

• Concatenating Strings

• Using a Bit Operator

Overview of Mathematical Operators

The following table describes the basic arithmetic operators you can use in Siebel eScript.

Operator	Description
=	Make one number equal to another number.
+	Add two numbers.
-	Subtract one number from another number.
*	Multiply two numbers.
/	Divide one number by another number.
%	Return a remainder after a division operation. It is a modulo.

The following examples use variables and arithmetic operators:

var i;

i = 2;     //i is now 2

i = i + 3; //i is now 5, (2 + 3)

i = i - 3; //i is now 2, (5 - 3)

i = i * 5; //i is now 10, (2 * 5)

i = i / 3; //i is now 3.333..., (10 / 3) 

i = 10;    //i is now 10

i = i % 3;  //i is now 1, (10 mod 3)

If uncertainty exists about how Siebel eScript might evaluate an expression, then it is recommended that you use parentheses. This recommendation is true even if you do not require parentheses to modify the sequence that Siebel eScript uses to evaluate expressions.

Using a Shortcut Operation to Do an Arithmetic Operation

A shortcut operation is a combination of the equal operator (=) with another operator. You can use a shortcut operation to reduce the amount of code you write. This technique does the following:

• To do an operation on the value that precedes the equal operator, it uses the value that comes after the equal operator.

• Saves the result in the value that precedes the equal operator.

To use a shortcut operation to do an arithmetic operation

• Add an operator immediately before the equal operator.

For example, instead of writing i = i + 3, you can write i += 3.

The following table describes the shortcut operators that you can use in Siebel eScript.

Shortcut Operation	Description
+=	Add a value to a variable.
-=	Subtract a value from a variable.
*=	Multiply a variable by a value.
/=	Divide a variable by a value.
%=	Return a remainder after a division operation.

The following example uses shortcut operators:

var i;

i += 3; //i is now 5 (2 + 3). Same as i = i + 3.

i -= 3; //i is now 2 (5 - 3). Same as i = i - 3.

i *= 5; //i is now 10 (2 * 5). Same as i = i * 5.

i /= 3; //i is now 3.333...(10 / 3). Same as i = i / 3. 

i = 10; //i is now 10

i %= 3;  //i is now 1, (10 mod 3). Same as i = i % 3.

Modifying the Sequence That Siebel eScript Uses to Evaluate an Expression

Siebel eScript evaluates the operators in an expression in the following order:

1. Arithmetic operators

2. Comparison operators

3. Logical operators

You can write code that modifies this order.

To modify the sequence that Siebel eScript uses to evaluate an expression

• Use parentheses to group operations.

Siebel eScript performs operations in parentheses before it performs operations that occur outside of parentheses. It performs multiplication operations and division operations in an expression before it performs addition operations and subtraction operations. You can use parentheses to modify this sequence.

The following table includes an example of how Siebel eScript calculates a grouped expression.

No Grouping	Equivalent	Not Equivalent
4 * 7 - 5 * 3 = 13 Siebel eScript calculates this expression as 28 - 15 = 13.	(4 * 7) - (5 * 3) = 13 Siebel eScript calculates this expression as 28 - 15 = 13.	4 * (7 - 5) * 3 = 24 Siebel eScript calculates this expression as 4 * 2 * 3 = 24.

Using Logical Operators and Conditional Expressions

Note the following:

• A logical operator is a type of operator that compares two values, and then determines if the result is true or false. A variable or any other expression can include true or false.

• A conditional expression is an expression that does a comparison.

You can use a logical operator to make a decision about the statements that reside in a script to run according to how Siebel eScript evaluates a conditional expression.

The following table describes the logical operators that you can use in Siebel eScript.

Logical Operator	Description
!	Not. Reverse of an expression. If (a+b) is true, then !(a+b) is false.
&&	And. If the value of every expression in the statement is true, then the entire statement is true. For example, if the first expression is false, then Siebel eScript does not evaluate the second expression because the entire expression is false.
||	Or. If the value of one expression in the statement is true, then the entire statement is true. For example, if the first expression is true, then Siebel eScript does not evaluate the second expression because the entire expression is true.
==	Equality. If the values of all expressions in the statement are equal to each other, then the entire statement is true. If the value of one expression is not equal to the value of any other expression, then the entire statement is false. Caution: The equality operator (==) is different from the assignment operator (=). If you use the assignment operator to test for equality, then your script fails because Siebel eScript assigns after the expression to a variable that precedes this expression. For more information, see Using the Equality Operator with a Strongly Typed Variable.
!=	Inequality. If the value of one expression is different from the value of any other expression, then the entire statement is true. If the value of all expressions in the statement are equal, then the entire statement is false.
<	Less than. If the expression is a < b, and if a is less than b, then the statement is true.
>	Greater than. If the expression is a > b, and if a is greater than b, then the statement is true.
<=	Less than or equal to. If the expression is a <= b, and if a is less than or equal to b, then the statement is true.
>=	Greater than or equal to. If the expression is a >= b, and if a is greater than or equal to b, then the statement is true.

Example of Using Logical Operators and Conditional Expressions

Assume you design a simple guessing game where you configure Siebel CRM to choose a number between 1 and 100, and the user attempts to guess the value of this number. The game provides feedback if the user is correct or if the user answer is higher or lower than the number that the game chooses. The following Siebel eScript code implements this guessing game. Assume that the GetTheGuess function is a custom function that gets the guess:

var guess = GetTheGuess(); //get the user input, which is 1, 2, or 3

target_number = 2;

if (guess > target_number)

{

   TheApplication().RaiseErrorText(“Guess is too high.”);

}

if (guess < target_number)

{

   TheApplication().RaiseErrorText(“Guess is too low.”);

}

if (guess == target_number);

{

   TheApplication().RaiseErrorText(“You guessed the number!”);

}

In this example, the action that Siebel eScript performs depends on if the value in the parenthesis in an If statement is true or false:

• True. It runs the statement block that follows this If statement.

• False. It ignores the statement block that follows this If statement and runs the script that occurs immediately after the statement block.

Using the Equality Operator with a Strongly Typed Variable

If ST eScript code does an equality operation, then it compares different objects depending on the following types of variables that are involved in the comparison:

• Typeless variable. It compares object values.

• Strongly typed variable. It compares object identities.

For more information, see Using Strongly Typed and Typeless Variables.

Example of Using the Equality Operator with Strongly Typed Variables

The comparison in the following example involves strongly typed variables. The result is always not equal because Siebel eScript compares object identities in this example. It does not compare object values:

function foo ()

{

  var oStr1 : String = new String ("aa");

  var oStr2 : String = new String ("aa");

  if (oStr1 == oStr2)

     TheApplication ().RaiseErrorText ("equal");

  else

     TheApplication ().RaiseErrorText ("not equal");

}

The result of the comparison in the following example is always not equal. The variables are typeless. The String is an object and Siebel eScript does object comparisons in the If statement:

function foo ()

{

  var oStr1 = new String ("aa");

  var oStr2 = new String ("aa");

  if (oStr1 == oStr2)

     TheApplication ().RaiseErrorText ("equal");

  else

     TheApplication ().RaiseErrorText ("no equal");

}

This topic describes how to make sure Siebel eScript compares the values of variables that reside in an equality operation.

To make sure Siebel eScript compares variable values in an equality operation

• Use the valueOf method.

For example:

function foo () 

{

 var oStr1 = new String ("aa"); 

 var oStr2 = new String ("aa"); 

 if (oStr1.valueOf () == oStr2.valueOf ()) 

    TheApplication ().RaiseErrorText ("equal");

 else 

    TheApplication ().RaiseErrorText ("no equal");

} 

• Use primitive data types.

For example:

function foo () 

{ 

 var oStr1 : chars = "aa" 

 var oStr2 : chars = "aa"; 

 if (oStr1 == oStr2) 

    TheApplication ().RaiseErrorText ("equal"); 

 else 

    TheApplication ().RaiseErrorText ("no equal"); 

}

Increasing or Decreasing the Value of a Variable

You can use the increment or decrement operator in the following ways:

• Before a variable. Siebel eScript modifies the variable before it uses it in a statement.

• After a variable. Siebel eScript modifies the variable after it uses it in a statement.

These operators add or subtract 1 from a value. For example, i++ is shorthand for i = i + 1.

To increment or decrement a variable

• To add 1 to a variable, you use the following operator:

  ++

• To subtract 1 from a variable, you use the following operator:

  --

The following example uses increment and decrement operators:

var i;
var j;
i = 4; //i is 4
j = ++i; //j is 5 and i is 5. Siebel eScript incremented i first.
j = i++; //j is 5, i is 6. Siebel eScript incremented i last.
j = --i; //j is 5, i is 5. Siebel eScript incremented i first.
j = i--; //j is 5, i is 4 Siebel eScript incremented i last.
i++; //i is 5. Siebel eScript incremented i.

Using Less Code to Write an Else Statement

The conditional operator is a type of operator that allows you to use less code when you write an Else statement. A statement that includes a conditional operator is more difficult to read than an If statement. It is recommended that you use a conditional operator only if the expressions in the If statements are brief.

The following format illustrates how the question mark (?) represents the conditional operator:

variable = expressionA ? expressionC : expressionC

where:

• expressionA is the expression that Siebel eScript evaluates first.

• expressionB is the expression that Siebel eScript evaluates if expressionA is true. If expressionA is true, then Siebel eScript replaces the value of the entire expression with the value of expressionB.

• expressionC is the expression that Siebel eScript evaluates if expressionA is true. If expressionA is false, then Siebel eScript replaces the value of the entire expression with the value of expressionC.

To use less code to write an Else statement

• Use a conditional operator instead of an Else statement.

Examples of Using the Conditional Operator

In the following example, the expression is true and Siebel eScript sets the value of variableA to 100:

variableA = ( 5 < 6 ) ? 100 : 200;

Consider the following example:

TheApplication().RaiseErrorText("Name is " + ((null==name) ? "unknown" : name));

If the name variable contains:

• A null value, then Siebel CRM displays the following text:

Name is unknown

• A value that is not null, such as Pat, then Siebel CRM displays the following text:

Name is Pat

Concatenating Strings

Concatenating is the act of stringing two items together in consecutive order. You can write code that concatenates two or more strings in Siebel eScript.

To concatenate strings

• Use the plus (+) operator between two strings.

Examples of Concatenating Strings

The following example uses the addition (+) operator between two strings:

var proverb = "A rolling stone " + "gathers no moss.";

This example sets the value of the proverb variable to the following text:

A rolling stone gathers no moss.

The following example concatenates a string and a number:

var newstring = 4 + "get it";

This example sets the value of the new string variable to the following text:

4get it

Using a Bit Operator

Siebel eScript includes operators that you can use to work directly on the bits that reside in a byte or in an integer. To use a bit operator, you must possess knowledge about bits, bytes, integers, binary numbers, and hexadecimal numbers. In most situations you do not need to use a bit operator.

The following table describes the bit operators you can use in Siebel eScript.

Operator	Description	Example
<<	Shift left.	i = i << 2
<<=	Equal shift left.	i <<= 2
>>	Signed shift right.	i = i >> 2
>>=	Equal signed shift right.	i >>= 2
>>>	Unsigned shift right.	i = i >>> 2
>>>=	Equal unsigned shift right.	i >>>= 2
&	Bitwise and.	i = i & 1
&=	Equal bitwise and.	i &= 1
|	Bitwise or.	i = i | 1
|=	Equal bitwise or.	i |= 1
^	Bitwise xor, exclusive or.	i = i ^ 1
^=	Equal bitwise xor, exclusive or.	i ^= 1
~	Bitwise not, complement.	i = ~i

Coding with Siebel eScript

This topic describes how to do some basic tasks that include Siebel eScript. It includes the following topics:

• Using Script Libraries

• Using Strongly Typed and Typeless Variables

• Declaring and Using Variables

• Determining the Data Type of a Variable

• Passing a Value to a Function

• Preventing a Floating-Point Error

• Using the Literal Value of a Special Character

• Running Browser Script When Siebel CRM Starts a Siebel Application

• Releasing an Object from Memory

• Monitoring the Performance of Your Script

Using Script Libraries

The ST eScript engine provides business service script libraries that assist you with developing components that are reusable and modular, which simplifies upgrades and maintenances. You can use script libraries to call global scripts. Script libraries provide the following capabilities:

• Allows you to write code that calls a business service function directly from anywhere in the scripting interface after you declare the business service. You are not required to write code that declares property sets or issue InvokeMethod calls.

• Allows you to write strongly typed methods for predefined business services. You can then use the Script Assist utility to write code that calls these business services. For more information, see Using Strongly Typed and Typeless Variables.

Using script libraries is optional. Siebel CRM supports all code written prior to Siebel 8.0.

Example of Calling a Business Service Function

The following example calls a method directly on the Data Transfer Service without declaring a property set. Calling a business service method directly results in scripts that are shorter and more readable:

var oBS : Service = TheApplication ().GetService ("Data Transfer Service");

oBS.SendData ("Name", "John Doe");

Example of a Creating Custom Method for a Business Service

You can write a custom method for a business service and make it available in Script Assist. The following example creates SendData, which is a custom wrapper method that resides on the Data Transfer Service:

function SendData (sTag : String, sValue : String)

{

  var oPS1 = TheApplication ().NewPropertySet ();

  var oPS2 = TheApplication ().NewPropertySet ();
  oPS1.SetProperty ("Tag", sTag);

  oPS1.SetProperty ("Value", sValue);
  this.InvokeMethod ("SendData", oPS1, oPS2)

}

You can write code that intercepts and modifies the calls to the Data Transfer Service in a central location in the SendData method.

Displaying a Custom Method in Script Assist

This topic describes how to display a custom method in Script Assist. For more information, see About the Script Assist Utility. For more information about setting an object property or about using the Server Script Editor to create, save, or compile a script, see Using Siebel Tools.

To display a custom method in Script Assist

1. Make a custom method available to the script libraries so that you can call it from Script Assist:

   1. Save the business service method script.

   2. Make sure the script does not contain compile errors.

      If a script library calls a function, then the compiler determines if argument types are valid and do not contain incompatibilities.

   3. In Siebel Tools, make sure the External Use property contains a check mark for the business service object.

2. To access Script Assist from the script editor, press CTRL + SPACE.

3. In your script, enter the name of a business service object followed by a period (.).

   Script Assist displays the default and custom scripted methods that are available for the business service object.

4. Choose the method you must add to your script.

Using Strongly Typed and Typeless Variables

A variable can include one of the following:

• Strongly typed. You specify the data type when you declare the variable. ST eScript code supports strong typing. Siebel CRM binds strong typing when you compile the code.

• Typeless. Siebel CRM determines the data type at run time. ST eScript code and T eScript code supports typeless variables.

A strongly typed variable typically improves performance over a typeless variable.

You can write code that strongly types all of the primitive data types and object data types. For more information, see About Primitive Data Types and About Composite Data Types.

Creating a Strongly Typed Variable

This topic describes how to create a strongly typed variable.

To create a strongly typed variable

1. Make sure Siebel Tools uses the ST eScript engine.

   For more information, see Using Siebel Tools.

2. When you declare the variable, make sure you add a colon (:) at the end of the variable name.

   For example:

   var VariableA:Date = new Date ();
   
   var VariableB:BusObject;
   
   var VariableC:BusComp;
   

Creating a Typeless Variable

This topic describes how to create a typeless variable.

To create a typeless variable

• Do not specify the data type when you declare the variable.

  For example:

  var VariableA = 0;
  
  var VariableB = new Date ();
  
  var VariableC = new BusObject;
  

  In this example, Siebel eScript sets the following types:

  • Sets VariableA as an integer

  • Sets VariableB as a date

  • Types VariableC as a business object

  The data type that Siebel CRM sets at run time persists until a subsequent operation causes the interpreter to modify the type again.

Declaring and Using Variables

A variable is an object that stores and represents information in a script. Siebel eScript can modify the value of a variable but it cannot modify the value of a literal. For example, to display a name literally, you must use the following code multiple times:

TheApplication().RaiseErrorText("Aloysius Gloucestershire Merkowitzky");

To simplify this code, the following code uses a variable:

var Name = "Aloysius Gloucestershire Merkowitzy";

TheApplication().RaiseErrorText(Name);

The value of the Name variable changes, which allows you to use shorter lines of code and to reuse the same lines of code.

About Local and Global Variables

Siebel eScript includes the following types of variables:

• Local. A variable that you declare in a function. You can write code that references a local variable only in the function where you declare the variable.

• Global. A variable that you declare in one of the following ways:

  • Declare the variable outside of a function.

  • Declare the variable in the general declarations section of the application object.

  You can write code that references or modify a global variable from the following items:

  • Any function that is associated with the Siebel object for which you declare the variable.

  • Any object in a Siebel application where you declare the variable.

  • Another Siebel application.

  • If you declare a global variable outside of a function, then you can reference it from any object that resides in the Siebel application where you declare this variable. For more information, see the following.

If you declare a local variable that uses the same name as a global variable, then you cannot reference this global variable from the function where you declare this local variable.

Siebel VB includes a Global statement. You cannot use this statement in Siebel eScript.

Declaring a Global Variable Outside of a Function

You can write code that declares a variable in a location other than in the declaration section. For example:

var global1 = 6;
function ABC()
{
   global1 = 8;
  global2 = 6;
}
var global2 = 8;

Using a Local Variable is Preferable to Using a Global Variable

It is recommended that you use a local variable where possible instead of a global variable for the following reasons:

• A local variable helps you create modular code that is easier to debug and modify.

• A local variable requires fewer resources.

• It is easier for other developers to understand how you use a local variable in a single function than it is to understand how you use a global variable across an entire Siebel application.

• If a subsequent development team encounters an object that you script with a global variable, then this team might not understand the use of the global variable. If the team uses this variable, then the team might introduce defects.

• The scope of a global variable is too large to meet the business requirement and often results in a variable whose lifecycle is not clear.

Instead of using a global variable, it is recommended that you configure Siebel CRM to pass an object as a parameter to a function so that you can control the scope of the parameter. If you are considering using a global variable, then you must consider this usage carefully. If you use a global variable, then do so only rarely and document it thoroughly.

Example of Declaring Local and Global Variables

The following example includes local and global variables:

var globalVariable = 1;

function Function1()

{

   var localVariable1 = 1;

   var localVariable2 = 3;

   Function2(d);

}



function Function2(e)

{

   var localVariable3 = 2

   ...

}

This example illustrates the following concepts:

• The globalVariable variable is global to the object where you declare it because it is declared outside of a function. Typically you declare all global variables in a general declarations section.

• To create a local variable, you declare it in a function. The following variables are local because this example declares them in a function:

  • localVariable1

  • localVariable2

  • localVariable3

• This example cannot use localVariable3 in Function1 because it is not defined in this function.

• This example uses the d variable in Function1. It uses the e parameter to pass the d variable to Function2.

The following code includes variables that are available to Function1 and Function2:

Function1(): globalVariable, localVariable1, localVariable2

Function2(): globalVariable, localVariable3, e

Declaring a Variable

This topic describes how to declare a variable.

To declare a variable

• Use the var keyword.

For example:

var perfectNumber;

You can write code that saves a value in a variable when you declare it. For example:

var perfectNumber = 28;

Declaring a Variable In a Statement Block

If you declare a variable in a statement block in a method, then you can reference this variable anywhere in the method, including from a statement block that resides in the method where you did not declare the variable.

Determining the Data Type of a Variable

You can use the typeof operator to determine and set the data type of a variable.

To determine the data type of a variable

• Use one of the following formats:

  • var result = typeof variable

  • var result = typeof(variable)

  To improve readability, you can place parentheses around the variable operand, which makes typeof look like the name of a function rather than an operator keyword. Using these parentheses is functionally the same as not using them. They have no impact on program execution.

Immediately after Siebel CRM encounters one of these code lines, it sets the contents of the variable to one of the following string values:

• boolean

• buffer

• function

• object

• number

• string

• undefined

Passing a Value to a Function

This topic describes how to write code that passes a value to a subroutine or a function through a variable or through a reference.

Passing a Value Through a Variable

Siebel eScript can pass a value to a function through a variable. This variable retains the value that it contained before Siebel eScript passes it even though the subroutine or function might modify the passed value. The following example includes this configuration:

var VariableA = 5;

var VariableB = ReturnValue(VariableA);



function ReturnValue(VariableC)

{

   VariableC = 2 * VariableC;

   return VariableC ;

}

The following occurs in this example:

• VariableA equals 5 and VariableB equals 10.

• VariableC contains a value only while the ReturnValue function runs.

• VariableC does not contain a value after the ReturnValue function finishes.

• Siebel eScript passes VariableA as a parameter to the ReturnValue function and it manipulates this value as VariableC.

• VariableA retains the value that it contained before Siebel eScript passed it.

Passing a Value Through a Reference

Siebel eScript can pass a variable to a subroutine or a function through a reference. However, you use a variable to pass a value for most methods. Each method determines if it can receive a value from a variable or a reference.

A subroutine or function can modify the value. The following example includes this configuration:

var VariableA = new Object;

VariableA.name = "Joe";

VariableA.old = ReturnName(VariableA)



function ReturnName(VariableB)

{

   var VariableC = VariableB.name;

   VariableB.name = “Vijay”;

   return VariableC

}

The following occurs in this example:

• Siebel eScript passes VariableA to the ReturnName function through a reference.

• VariableB receives a reference to the object, but it does not receive a copy of this object.

• VariableB can reference every property and method of VariableA.

• The ReturnName function modifies the value in VariableB.name to Vijay. The value in VariableA.name also becomes Vijay.

• The Return statement passes a value back to the function that calls it. Siebel CRM does not run any code in a function that follows the Return statement. For more information, see Return Statement of a Function Object.

Preventing a Floating-Point Error

Caution: Saving a floating-point number in a variable might cause a loss in precision due to a memory limitation for decimal-to-binary conversion.

Siebel CRM can store a decimal number that does not convert to a finite binary representation with only a small precision error. For example, the following statement might result in Siebel CRM storing VariableA as 142871.450000000001:

var VariableA = 142871.45

A small precision error will likely have little effect on the precision of a subsequent calculation, depending on the context where you use the number.

A number might be too large for the field that Siebel CRM uses to display it, resulting in an error message that is similar to the following:

Value too long for field %1 (maximum size %2)

To prevent a floating-point error

• Use the Convert Number to Fixed Decimal Method method at an appropriate location in the calculation or when you save the value in a variable.

  For example, use x.toFixed(2) in a calculation instead of using VariableA. For more information, see Convert Number to Fixed Decimal Method.

Using the Literal Value of a Special Character

Each of the following characters possesses a special programmatic meaning in Siebel eScript:

• Double quotes (")

• Single quote (')

• Semi-colon (;)

• Ampersand (&)

• Hard return

In some situations, you might need to use the literal value of one of these characters. For example:

• Display quotation marks around a phrase in the Siebel client.

• Add a carriage return in a text file.

• Specify a file system path.

To use the literal value of a special character

• Precede the special character with two backslashes (\\).

  You must use two backslashes in Siebel eScript. It recognizes a single backslash as indicating that the next character identifies a character combination. For more information, see How Siebel eScript Handles Special Characters In a String.

Running Browser Script When Siebel CRM Starts a Siebel Application

You can configure Siebel CRM to run Browser Script when it starts a Siebel application. Siebel CRM normally runs code in the declaration section of the Browser Script for a business service when it starts this application. It interprets any code that exists in the general declaration section as HTML. When it loads this application in the Browser, it attaches each Browser script as a Script tag in an HTML page. This configuration allows you to use the general declaration section as the Browser counterpart of the Application Start Server event.

To run Browser script when Siebel CRM starts a Siebel application

• Use code in the general declaration section of the Browser script.

Releasing an Object from Memory

You must explicitly release from memory the following object types when your code no longer requires them:

• Application

• Business component

• Business object

• Configuration item

• CTI data

• CTI service

• Property set

• Web applet

• Web service

This situation is true for T eScript and ST eScript for Browser script and for Siebel VB.

To release an object from memory

• Set the object as a Null object.

  For more information, see Null Data Type.

Monitoring the Performance of Your Script

Starting with Siebel CRM version 8.1, the ST eScript engine allows you to monitor the performance of your script in Siebel CRM. You can identify parts of a script that consumes the most time to process, and then modify it to make it more efficient. Siebel Tools displays profile information in the Tools Script Performance Profiler window. You can export this information to a text file. For more information, see Using Siebel Tools.

Guidelines for Using Siebel eScript

This topic describes guidelines for using Siebel eScript. It includes the following topics:

• Make Sure You Use the Correct Format for Names

• Make Sure You Use the Correct Case

• Use Expressions, Statements, and Statement Blocks

• Use a Primitive Data Type Instead of an Object Data Type

• Use White Space to Improve Readability

• Use Comments to Document Your Code

• Make Sure the JavaScript Interpreter Can Run a Function

This topic describes only some of the guidelines for using Siebel eScript. For more guidelines, see the topic about guidelines for using Siebel VB and Siebel eScript in Siebel Object Interfaces Reference.

Make Sure You Use the Correct Format for Names

A variable name or a function name must include only the following characters:

• Uppercase ASCII letters. For example, ABCDEFGHIJKLMNOPQRSTUVWXYZ.

• Lowercase ASCII letters. For example, abcdefghijklmnopqrstuvwxyz.

• Digits. For example, 0123456789.

  • Underscore (_).

  • Dollar sign ($).

A variable name or a function name must use the following format:

• Must begin with a letter, an underscore (_), or a dollar sign ($).

• Cannot include any special characters. For more information, see Special Characters.

• Cannot include white space. Siebel eScript uses white space to separate names. For more information, see Use White Space to Improve Readability.

• Cannot include a reserved word. For more information, see Reserved Words.

• Can include any length.

The following example names are valid:

George

Martha7436

annualReport

George_and_Martha_prepared_the_annualReport

$alice

CalculateTotal()

$SubtractLess()

_Divide$All()

The following example names are not valid:

1george

2nancy

this&that

Martha and Nancy

What?

=Total()

(Minus)()

Add Both Figures()

Special Characters

The following information lists the characters that Siebel eScript recognizes as special characters.

Special Character	Description
<	Less than symbol.
>	Greater than symbol.
&	Ampersand symbol.
|	Pipe symbol.
=	Equal to sign.
!	Exclamation point.
*	Asterisk.
/	Forward slash.
%	Percentage symbol.
^	Caret symbol.
~	Tilde symbol.
?	Question mark.
:	Colon.
{	Open brace.
}	Close brace.
;	Semi-colon.
(	Open parenthesis.
)	Close parenthesis.
[	Open bracket.
]	Close bracket.
.	Period.
‘	Single quote.
"	Double quote.
'	Apostrophe.
#	Pound symbol.

Reserved Words

The following words have special meaning in Siebel eScript. You cannot write code that uses any of them as a variable name or a function name:

• break

• case

• catch

• class

• const

• continue

• debugger

• default

• delete

• do

• else

• enum

• export

• extends

• false

• finally

• for

• function

• if

• import

• in

• new

• null

• return

• super

• switch

• this

• throw

• true

• try

• typeof

• while

• with

• var

• void

Make Sure You Use the Correct Case

Siebel eScript is case-sensitive. For example, the testvar variable is different from the TestVar variable. Each of these variables can exist in a script at the same time. The following example defines two different variables:

var testvar = 5;

var TestVar = "five";

The name of a method or function in Siebel eScript is case-sensitive. For example, the following code creates an error on the Siebel Server:

TheApplication().RaiseErrorText("an error has occurred");

The following example creates an error in a Siebel application:

TheApplication().raiseerrortext("an error has occurred");

A control statement is case-sensitive. For example, the following statement is valid:

while 

The following statement is not valid:

While

Use Expressions, Statements, and Statement Blocks

An expression includes two or more terms that perform a mathematical or logical operation. These terms are typically variables or functions that you can use with an operator to produce a string or numeric result. You can write code that uses an expression to configure Siebel eScript to do the following work:

• Perform a calculation.

• Manipulate a variable.

• Concatenate a string.

The following example statement includes an expression. It computes a sum and saves it in a variable:

var TestSum = 4 + 3

Note the following:

• Siebel CRM runs Siebel eScript code one statement at a time from the beginning of the code to end of the code.

• You can use a semicolon at the end of a statement, although Siebel eScript does not require this format.

• To make your script easier to read and edit, it is recommended that you write each statement on a separate line, with or without a semicolon.

• A statement block is a group of statements that Siebel eScript treats as one statement. You use curly brackets ({}) to enclose a statement block. To simplify reading, it is recommended that you indent the statements in a statement block.

Running Statements in a Loop

A While statement is a type of statement that causes Siebel eScript to run the statement that occurs immediately after the While statement in a loop. If you enclose multiple statements in curly brackets, then Siebel eScript treats them as one statement and runs them in the loop. The following example includes this usage:

while( ThereAreUncalledNamesOnTheList() == true)

{

   var name = GetNameFromTheList();

   CallthePerson(name);

   LeaveTheMessage();

}

Siebel eScript treats the three lines that occur after the While statement as one unit. The brackets cause Siebel eScript to run the script through each line until it calls every name that resides in the list. If you remove these brackets, then it does the following:

• Runs the loop only for the first line.

• Processes the names on the list but only calls the last name.

Use a Primitive Data Type Instead of an Object Data Type

It is recommended that you use an object only if you must use a property that is specific to this object type. If an equivalent primitive data type exists, then use the primitive. A primitive data type provides superior performance. An object data type consumes more resources than a primitive data type.

The following table lists primitive data types that are equivalent to object data types. For example, if you do not need to use a string-specific object or conversion method, then use the chars primitive instead of a String object.

Primitive Data Type	Object Data Type
Chars	String
Float	Number
Bool	Boolean

Use White Space to Improve Readability

A white-space character is a type of character that determines the spacing and placement of text in your code. Each of the following items is an example of a white-space character:

• Space

• Tab

• Carriage-return

• New line

White space makes your code easier to read. Siebel eScript ignores white space characters.

A line of script ends with a carriage-return character. Each line is typically a separate statement. In some editors a line ends with a carriage-return and the following linefeed pair:

\r\n

Siebel eScript typically interprets as white space one or more white-space characters that exist between names of methods and functions. Each of the following Siebel eScript statements are equivalent to one another:

var x=a+b

var x = a + b

var x =     a     +     b

var x = a+

        b

White space separates the names, methods, functions, and variables. For example, ab is one variable name, and a b are two variable names. The following example is valid:

var ab = 2

The following example is not valid:

var a b = 2

Some developers use spaces and not tabs because tab size settings vary from editor to editor. If a developer uses only spaces, then the script format is consistent across editors.

Using White Space in a String Literal Can Cause Errors

Caution: Siebel eScript treats white space in a string literal differently from how it treats white space that occurs elsewhere. Placing a line break in a string causes Siebel eScript to treat each line as a separate statement. Each of these statements contains an error because they are not complete. To avoid this situation, you must keep string literals on a single line or create separate strings, and then use the string concatenation operator to concatenate them.

For example:

var Gettysburg = "Fourscore and seven years ago, " +

"our fathers brought forth on this continent a " +

"new nation.";

For more information, see Concatenating Strings.

Use Comments to Document Your Code

A comment is text in a script that you can use to document the script. It can describe the intent of the code flow, which simplifies modifications and debugging. Siebel eScript skips comments. Siebel eScript includes the following types of comments:

• End-of-line comment. Begins with two forward slashes (//). It ignores any text that occurs from after these slashes to the end of the current line. It begins interpreting the code that occurs on the next line.

• Statement block comment. Begins with a forward slash and an asterisk (/*). Ends with an asterisk and a forward slash (*/). Text between these markers is a comment even if the comment extends over multiple lines. You cannot write code that includes a statement block comment in a statement block comment. You can include an end-of-line comment in a statement block comment.

The following code includes valid comments:

// this is an end of line comment



/* this is a statement block comment.

This is one big comment block.

// this comment is okay in the statement block.

The interpreter ignores it.

*/



var FavoriteAnimal = "dog"; // except for poodles



//This line is a comment but

var TestStr = "This line is not a comment.";

Make Sure the JavaScript Interpreter Can Run a Function

If a function is unique to Siebel eScript, then you must make sure that the JavaScript interpreter that runs the script supports Siebel eScript functions. Avoid using a function that is unique to Siebel eScript in a script that Siebel CRM might use with a JavaScript interpreter that does not support the function.