2About Siebel eScript
About Siebel eScript
This chapter describes Oracle’s Siebel eScript. It includes the following topics:
Overview of Siebel eScript
Siebel eScript is a programming language that is syntactically and semantically compatible with JavaScript. It includes an editor, debugger, interpreter, and compiler. It runs on the Windows and UNIX operating systems.
JavaScript is typically part of a Web browser and can run while the user is connected to the Internet. Siebel eScript is part of Siebel CRM. The Siebel Application Object Manager interprets it at run time. You do not require a Web browser to run it. It provides access to the hard disk and other parts of the Siebel client or Siebel Server. ECMAScript does not provide this access.
Siebel Tools allows you to configure Siebel CRM without scripting. It is recommended that you use Siebel eScript only after you determine that you cannot use any other tool. For more information, see the chapter about using Siebel eScript in Siebel Object Interfaces Reference on Siebel Bookshelf.
About Siebel eScript Code
Siebel CRM uses two versions of Siebel eScript code:
T eScript code. Compiled by the original T eScript engine.
ST eScript code. Compiled by the ST eScript engine beginning with Siebel CRM version 8.0. Siebel CRM introduced this code in Siebel CRM version 7.8. ST eScript code is the default code beginning with Siebel CRM version 8.0.
This book mentions these code versions only if differences exist between how the code functions.
Features of ST eScript Code
ST eScript code includes the following features. T eScript code does not include these features:
Strong typing of variables. Sets the data type of a variable when you declare the variable. For more information, see Using Strongly Typed and Typeless Variables.
Script Assist utility. For more information, see About the Script Assist Utility.
Fix and Go feature. Allows you to edit and debug a script without recompiling it.
ToolTip feature. Displays method signature data after you enter a method name in the Script Editor.
Script profiling. For more information, see Monitoring the Performance of Your Script.
For more information about these features, see Using Siebel Tools.
Compatibility Between ST eScript Code and T eScript Code
ST eScript code is mostly backward compatible with T eScript code. The following table describes features that are not backward compatible.
| Feature | Description |
|---|---|
Strong typing |
For more information, see Using Strongly Typed and Typeless Variables. |
Comparison operations |
ST eScript code does the following:
If you are not aware of these differences, then the results of a comparison operation that involves strongly typed variables might be misleading. For more information, see Using Logical Operators and Conditional Expressions. |
Implicit variable type conversion |
Siebel eScript does an implicit conversion differently depending on if a variable is strongly typed or if it is typeless. For more information, see How Siebel eScript Converts Data Types. |
Methods |
Siebel eScript restricts the parameters in some methods differently depending on if you use ST eScript code or T eScript code. If it restricts these parameters differently, then this book describes those differences. For an example, see Set Array Length Method. |
Properties |
For more information, see Overview of Regular Expression Methods. |
Commands |
ST eScript code does not support the #Define statement or the #If statement. As an alternative, you can use a Var statement. For example, consider the following code: #define MY_DEFINE "abc" The following code replaces the #Define statement with the Var statement: var MY_DEFINE = "abc"; |
Objects and arrays |
For more information, see Referencing Objects and Arrays. |
Referencing Objects and Arrays
If you write code that references an array item, an object function, or object data, and:
You use T eScript code. Siebel eScript automatically creates a new object.
You use ST eScript code. Siebel eScript does not automatically create a new object. If you use ST eScript code, then you must configure Siebel eScript to explicitly initialize the object.
Referencing Object Functions or Data
The following script runs correctly using T eScript code but fails at runtime using ST eScript code:
var oArr = new Array (); oArr[0].m_Data =1;
You must configure Siebel eScript to initialize the data object that it references so that the script runs correctly with ST eScript code. For example:
var oArr = new Array (); oArr[0] = new Object (); oArr[0].m_Data =1;
The following script runs correctly using T eScript code but fails at runtime using ST eScript code:
var oArr = new Array (); oArr[2][3].m_Data = 2;
You must configure Siebel eScript to initialize the data object that it references so that the script runs correctly with ST eScript code. For example:
var oArr = new Array (); oArr[2] = new Array (); oArr[2][3] = new Object (); oArr[2][3].m_Data = 2;
Reverting ST eScript Code to T eScript Code
If you use ST eScript code, then you can revert this code back to T eScript code. This technique is not recommended.
To revert ST eScript code to T eScript code
Create a service request or call Oracle Global Customer Support.
For help with reverting ST eScript code to T eScript code, create a service request (SR) on My Oracle Support. Alternatively, you can phone Oracle Global Customer Support directly to create a service request or get a status update on your current SR. Support phone numbers are listed on My Oracle Support.
In Siebel Tools, turn off the ST eScript engine.
For more information, see Using Siebel Tools.
Remove any script that you typed prior to compiling with the ST eScript engine.
Do a full compile of all objects in the repository.
About the Script Assist Utility
The Script Assist utility is a feature in Siebel Tools that helps you write ST eScript code. Starting with Siebel CRM version 8.0, Script Assist can access information about object definitions in the runtime repository that your script references, and then display this information in the Script Assist window.
Script Assist limits the choices you can make according to the information that the runtime repository contains. This feature helps prevent scripting errors and simplifies the scripting process. For example, it prevents you from writing code that causes Siebel CRM to write to a read-only field, or to get a value from a field that does not exist in the object. It displays the required and optional parameters for the following items:
Siebel methods
Global methods
Global functions
Custom functions
Methods available for InvokeMethod calls
To identify the object that your script references, Script Assist can use the following object reference key word in a script and display the appropriate fields for this object:
this
For more information about Script Assist, see Using Siebel Tools.
The following information lists the objects and methods that Script Assist can access in the runtime repository.
| Object | Method |
|---|---|
Applet |
Script Assist can access the following methods:
|
Application |
Script Assist can access the following methods:
|
Business Component |
Script Assist can access the following methods:
|
Business Object |
GetBusComp |
Business Service |
InvokeMethod |
About Data Types and Numbers
This topic describes data types in Siebel eScript. It includes the following topics:
For more information, see Determining the Data Type of a Variable.
About Primitive Data Types
A primitive data type is a type of data that Siebel eScript provides as a fundamental part of the code. It does not possess other properties or functions.
The bool, chars, and float data types must use lowercase.
Bool Data Type
The bool data type defines and manipulates a Boolean object. A Boolean value is true or false.
Chars Data Type
The chars data type defines and manipulates a string. A chars value is a sequence of alphanumeric characters. It can include any sequence of 16-bit, unsigned integers.
Float Data Type
The float data type defines and manipulates a floating point number.
Integer is not a Siebel eScript data type. You can write code that uses a float variable. Some code that expects an integer variable converts a float variable to an integer.
Undefined Data Type
If Siebel CRM saves nothing in a variable, then it is undefined. An undefined variable occupies space until Siebel CRM saves a value in it. When Siebel CRM saves a value in a variable, it modifies the type of the variable according to the value.
The following example determines if a variable is undefined:
var test;
if (typeof test == "undefined")
TheApplication().RaiseErrorText("test is undefined");
About Composite Data Types
This topic describes the composite data types that Siebel eScript uses. A composite data type is a complex type of data that can include properties and functions.
Overview of the Object Data Type
The ECMAScript standard uses the following description for an object:
A member of the type Object. It is an unordered collection of properties, each of which includes a primitive value, object, or function. A function stored in a property of an object is referred to as a method.
Siebel eScript does not use a class hierarchy that conforms to this ECMAScript standard. Instead, it instantiates an object in the following ways:
As an Object type
From an object that it instantiates as an Object type
These objects are new object types that Siebel eScript can use to instantiate other objects. Each object includes an implicit constructor function that it implements through the following command:
new
You can configure Siebel eScript to add properties dynamically to an object. An object inherits all the properties of the objects that reside in the ancestral chain of the object.
The object type known as Object is a generic object type. If you declare an object as an Object type, then it does not inherit properties from any object.
For more information, see Use a Primitive Data Type Instead of an Object Data Type.
Boolean Data Type
The value of a Boolean object is a bool value, which is true or false. It is a property of the Boolean object. If you use a Boolean variable in a numeric context, then Siebel eScript does the following conversion:
If the value of a bool variable is true, then it converts this value to 1.
If the value of a bool variable is false, then it converts this value to 0.
To create a Boolean object, you use the Boolean constructor in the type of expression:
new
String Data Type
The string value is a chars value. Siebel eScript adds it as a property of the String object. A pair of double or single quotation marks brackets a string. For example:
"I am a string" 'so am I' "344"
In this example, the 344 string is an array of characters. The number 344 is a value that Siebel eScript can use in a numeric calculation.
To create a string data type, you use the String constructor in the following type of expression:
new
Siebel eScript does one of the following, depending on the context:
Converts a string to a number
Converts a number to a string
For more information, see How Siebel eScript Converts Data Types.
Number Data Type
The value of a number is a float value. It is a property of the Number object.
To create a number object, you use the Number constructor in the following type of expression:
new
For more information, see About Numbers.
Array Data Type
An array is a series of data that Siebel eScript stores in a variable. Each datum is associated with an index number or string. The following example illustrates how Siebel eScript stores data in an array:
var Test = new Array; Test[0] = "one"; Test[1] = "two"; Test[2] = "three";
In this example, the Test variable is an array that includes three strings. You can write code that uses an array variable as one unit. To reference a string individually, you can append the bracketed index of the element after the array name.
To reference a property:
An array uses an index.
An object uses a property name or a method name.
For more information, see Array Methods.
Null Data Type
The null object indicates that a variable is empty. It does not contain a value, although it might have previously contained a value. The following term identifies a null data type:
null
The following keyword allows you to compare a value to a null object:
null
Null includes a literal representation. The following example is valid:
var test = null;
Siebel eScript can compare any variable that contains a null value to a null literal.
Other Object Types That Siebel eScript Supports
The following information lists other object types that Siebel eScript supports.
| Object | Description |
|---|---|
Application |
For more information, see Siebel Object Interfaces Reference. |
BLOB |
For more information, see BLOB Methods. |
BLOB Descriptor |
For more information, see About the blobDescriptor. |
Buffer |
For more information, see Buffer Methods. |
Business Component |
For more information, see Overview of Date Methods. |
Business Object |
For more information, see Siebel Object Interfaces Reference. |
CfgItem |
The CfgItem object is a Siebel Product Configuration object. |
Clib |
For more information, see Overview of the Clib Object. |
CTIData |
For more information, see Siebel CTI Administration Guide. |
CTIService |
For more information, see Siebel CTI Administration Guide. |
Date |
For more information, see Overview of Date Methods. |
Exception |
For more information, see Function Object. |
File |
For more information, see Clib Open File Method. |
Math |
For more information, see Mathematical Methods. |
Property Set |
For more information, see Siebel Object Interfaces Reference. |
Regular Expression |
For more information, see Regular Expression Methods. |
SELib |
For more information, see Siebel Library Methods. |
Service |
For more information, see Siebel Object Interfaces Reference. |
Web Applet |
For more information, see Siebel Object Interfaces Reference. |
Properties and Methods of Common Data Types
Common data types include properties and methods that you can use with any variable of this type. Any string variable can use any string method. Examples of common data types include a number or string. For example, assume you use a numeric variable named VariableA and you must convert it to a string. The following example illustrates how you can use the toString method to convert a numeric variable to a string:
var VariableA = 5; var VariableB = num.toString();
After this code finishes, VariableA contains the number 5 and VariableB contains the string 5.
The following methods are common to variables:
ValueOf method. Returns the value of a variable. Value is an implicit property of some objects, including number, string, and Boolean objects.
ToString method. Returns the value of a variable that is expressed as a string. Value is an implicit property of number and Boolean objects.
How Siebel eScript Converts Data Types
Siebel eScript implicitly converts data types in many mixed-type contexts. You must use conversion methods to make sure your code does the required conversions. For more information, see Conversion Methods.
Concatenation Can Cause a Conversion
Siebel eScript converts the data type of a typeless variable in the following situations:
If you write Siebel eScript code that subtracts a string from a number, or that subtracts a number from a string, then it converts this string to a number and subtracts the two values.
If you write Siebel eScript code that adds a string to a number, or that adds a number to a string, then it converts this number to a string and concatenates the two strings.
Siebel eScript must always convert a string to a base 10 number. This string must contain only digits. For example, the following string does not convert to a number because Text is meaningless as part of a number in Siebel eScript:
110Text
The following examples result in Siebel eScript doing a conversion:
s = "dog" + "house" // s = "doghouse", two strings are concatenated. t = "dog" + 4 // t= "dog4", a number is converted to a string u = 4 + "4" // u = "44", a number is converted to a string v = 4 + 4 // v = 8, two numbers are added w = 23 - "17" // w = 6, a string is converted to a number
Using a Conversion Method
You must use a conversion method to make sure Siebel eScript does conversions when it adds, subtracts, or does other arithmetic operations. The following example uses a conversion method to convert a string input to a numeric value:
var n = "55"; var d = "11"; var division = Clib.div(ToNumber(n), ToNumber(d));
Use can use the parseFloat method of the global object to specify a more stringent conversion. For more information, see Convert String to Floating-Point Number Method.
You must use a conversion method in situations where Siebel eScript does not do a conversion. Siebel eScript includes many global methods that convert data types. For more information, see Conversion Methods.
Setting the Data Type Can Cause a Conversion
Siebel eScript does conversions differently depending on if the variable is typeless or strongly typed. For more information, see Using Strongly Typed and Typeless Variables.
How Siebel eScript Converts a Typeless Variable
If Siebel eScript sets the data type for a typeless variable, then it converts this variable only to another typeless variable. For example, the following examples result in Siebel eScript converting VariableA to a string:
var VariableA = 7.2; var VariableB = “seven point 2” VariableA = VariableB;
How Siebel eScript Converts a Strongly Typed Variable
The following table describes how Siebel eScript converts a strongly typed variable. In this table, assume that Siebel eScript must convert VariableA to VariableB.
| VariableA Type | VariableB Type | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Value | Chars | Bool | Float | Object | String | Number | Boolean | Other | |
Value |
Same |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Chars |
Yes |
Same |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes W |
Bool |
Yes |
Yes |
Same |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Float |
Yes |
Yes, W |
Yes |
Same |
Yes, W |
Yes, W |
Yes |
Yes |
Yes, W |
Object |
Yes |
Err |
Err |
Err |
Same |
None |
None |
None |
None |
String |
Yes |
Yes |
Err |
Err |
Err |
Same |
Err |
Err |
Err |
Number |
Yes |
Err |
Err |
Yes |
Err |
Err |
Same |
Err |
Err |
Boolean |
Yes |
Err |
Yes |
Err |
Err |
Err |
Err |
Same |
Err |
Other |
Yes |
Err |
Err |
Err |
Err |
Err |
Err |
Err |
Same |
The previous table uses the following abbreviations:
Yes. Siebel eScript converts the variable.
W. Siebel Tools might display a message when it compiles the script. This message warns that the conversion might not occur. The warning and conversion depend on the properties of the variables that are involved when Siebel eScript sets the data type.
Err. A compilation error occurs.
None. No conversion is required. A conversion is not typically required to modify an Object variable to a specialized object type.
Same. VariableA and VariableB are of the same type.
-
Value. Indicates a typeless variable. It describes the conversion that Siebel eScript does in the following situations:
Convert a strongly typed variable to a typeless variable.
Convert a typeless variable to a strongly typed variable.
Other. Indicates predefined types and custom types that are not the following types:
Object
String
Number
Boolean
About Numbers
This topic describes the types of numbers that you can use with Siebel eScript. Siebel eScript treats a number that contains a character other than a decimal point as a string. For example, the number 100,000 is a string, including the comma. The exception is hexadecimal numbers and scientific notation.
The number types that this topic describes are not data types. You cannot write code that uses one of these number types as a data type in the declaration of a strongly typed variable. For more information, see Using Strongly Typed and Typeless Variables.
Integer Numbers
An integer number is a positive whole number, a negative whole number, or zero. Siebel eScript recognizes the following:
An integer constant or an integer literal in decimal, hexadecimal, or octal notation.
A decimal constant or a decimal literal in decimal representation.
You cannot write code that strongly types a variable as an integer. You can write code that uses the float primitive or the value of the float primitive as an integer. For more information, see Using Strongly Typed and Typeless Variables.
Hexadecimal Numbers
A hexadecimal number is a number that uses base 16 digits. It uses digits from the following sets:
0 through 9
A through F
a through f
The following format precedes a hexadecimal number:
0x
A hexadecimal number is not case-sensitive in Siebel eScript.
The following table lists example hexadecimal numbers and their decimal equivalents.
| Hexadecimal Number | Decimal Number |
|---|---|
0x1 |
1 |
0x01 |
1 |
0x100 |
256 |
0x1F |
31 |
0x1f |
31 |
0xABCD |
43981 |
var a = 0x1b2E |
var a = 6958 |
Octal Numbers
An octal number is a number that uses base 8 digits. It includes digits from the following set:
0 through 7
A zero precedes an octal number.
The following table lists example octal numbers and their decimal equivalents.
| Octal Number | Decimal Number |
|---|---|
00 |
0 |
05 |
5 |
077 |
63 |
var a = 0143 |
var a = 99 |
Floating Point Numbers
A floating-point number is a number that includes a whole part and a fractional part. A decimal separates these parts. For example, 10.33. Some developers refer to a floating-point number as a float. The float data type is not a floating-point number. For more information, see Float Data Type.
For more information, see Preventing a Floating-Point Error.
Floating Decimal Numbers
A floating decimal number is a number that uses the same digits as a decimal integer but uses a period to indicate the fractional part of the number. For example:
0.32, 1.44, 99.44 var a = 100.55 + .45;
Scientific Numbers
A scientific number is a number that uses decimal digits and exponential notation. The following items represent exponential notation:
eE
A scientific number is useful if you must use very large or very small numbers. Scientific notation is also known as exponential notation.
The following table lists example scientific numbers and their decimal equivalents.
| Scientific Number | Decimal Number |
|---|---|
4.087e2 |
408.7 |
4.087E2 |
408.7 |
4.087e+2 |
408.7 |
4.087E-2 |
0.04087 |
var a = 5.321e31 + 9.333e-2 |
var a = 53210000000000000000000000000000 + 0.09333 |
NaN Numbers
NaN is a value that is an abbreviation for the following phrase:
not a number
NaN is not a data type. NaN does include a literal representation. To test for NaN, you must use the isNaN function. The following example illustrates this usage:
var Test = "Test String";
if (isNaN(parseInt(Test)))
TheApplication().RaiseErrorText("Test is Not a Number");
If the parseInt function attempts to parse Test String into an integer, then it returns NaN because Test String does not represent a number.
Numeric Constants
You can write code that references a numeric constant as a property of the Number object. A numeric constant does not include a literal representation.
The following table describes some numeric constants.
| Numeric Constant | Value | Description |
|---|---|---|
|
1.7976931348623157e+308 |
Largest positive number. |
|
2.2250738585072014e-308 |
Smallest positive nonzero value. |
|
NaN |
Not a number. |
|
Infinity |
Number greater than |
|
-Infinity |
Number less than |
About Functions and Methods
A function is an independent section of code that does the following:
Receives information
Performs some action on this information
Returns a value to the item that called it
It begins with the following statement:
Function functionname
It ends with the following statement:
End Function
You use the same format as you use with a variable to name a custom function. You can write code that uses any valid variable name as a function name. It is recommended that you use a name that describes the work that the function performs.
You can write code that calls a function repeatedly from various objects or script. It is similar to a subroutine. To call a function, you must know what information the function requires as input and what information it provides as output. This book describes the predefined functions that come with Siebel eScript. You can write code that uses these functions any time you use the Siebel eScript interpreter.
You can write code that uses a function anywhere that you can use a variable. To use a function, you do the following:
To declare it, you use the function keyword.
To determine the data that Siebel eScript must pass to the function, you include the function operator. To include this operator, you use a pair of parentheses immediately after the function name. For example:
TheApplication.RaiseErrorText()
A Siebel VB method is a function that is part of an object or class. It can include a predefined procedure that you can use to call a function that does an action or a service for an object.
A Siebel VB statement is a complete instruction.
For more information, see Passing a Value to a Function.
Example of a Function
The TheApplication.RaiseErrorText function is an example of a function that allows you to display formatted text if an error occurs. It does the following work:
Receives a string from the function that calls it
Displays this string in an alert box in the Siebel client
Stops the script
About Function Scope
A function is global. Siebel eScript can call it from anywhere in a script in the object where you declare it. The examples in this topic achieve the following results:
The code passes the 3 and 4 literals as parameters to the SumTwo function.
The SumTwo function includes corresponding a and b variables. These variables contain the literal values that Siebel eScript passes to the function.
Example of Calling a Function as a Function
The following example calls the SumTwo function:
function SumTwo(a, b)
{
return (a + b)
}
TheApplication().RaiseErrorText(SumTwo(3, 4));
The following example uses a method of the global object to call the SumTwo function:
function SumTwo(a, b)
{
return (a + b)
}
TheApplication().RaiseErrorText(global.SumTwo(3, 4));
The Arguments Property of a Function
The arguments property of a function is a list of the arguments that Siebel eScript passes to the function. The first argument is arguments[0], the second argument is arguments[1], and so on. You can write code that references the arguments property for a function only in that same function.
You can configure a function that includes an indefinite number of arguments. The following example uses a variable number of arguments, and then returns the sum:
function SumAll()
{
var total = 0;
for (var ssk = 0; ssk < arguments.length; ssk++)
{
total += arguments[ssk];
}
return total;
}
About Recursive Functions
A recursive function is a type of function that calls itself or that calls another function that calls the first function. Siebel eScript allows recursion. Each call to a function is independent of any other call to this function. If a function calls itself too many times, then the script runs out of memory and aborts.
In the following example, the factor function calls itself so that it can factor a number. Factoring is an appropriate use of recursion because it is a repetitive process where the result of one factor uses the same rules to factor the next result:
function factor(i) //recursive function to print factors of i,
{// and return the number of factors in i
if ( 2 <= i )
{
for ( var test = 2; test <= i; test++ )
{
if ( 0 == (i % test) )
{
// found a factor, so print this factor then call
// factor() recursively to find the next factor
return( 1 + factor(i/test) );
}
}
}
// if this point was reached, then factor not found
return( 0 );
}
Error Checking with Functions
If a function fails, then some functions return a special value. Consider the following example:
To allow a script to read from or write to a file, the Clib.fopen method opens or creates this file.
If the script calls the Clib.fopen method but this method cannot open a file, then the method returns null.
If the script then attempts to read from or write to this file, then Siebel CRM creates an error.
To prevent this error, you can use the following code to determine if Clib.fopen returns null when it attempts to open a file. If it does return null, then you can write code that aborts the script and displays an error message:
var fp = Clib.fopen("myfile.txt", "r");
var fp = Clib.fopen("myfile.txt", "r");
if (null == fp)//make sure null is not returned
{
TheApplication().RaiseErrorText("Error with fopen as returned null " +
"in the following object: " + this.Name() + " " + e.toString() + e.errText());
}
For more information, see Overview of the Clib Object.
Where Data Resides
Data in a script resides in a literal or in a variable. The following example includes variables and literals:
var TestVar = 14; var aString = "test string";
This code does the following:
Saves the following literal value to the TestVar variable:
14
Saves the following literal value to the aString variable:
test string
After you save a literal value in a variable, you can reference this variable anywhere in the script where you declare the variable.