5Methods Reference
Methods Reference
This chapter describes reference information for methods that you can use in Siebel eScript. It includes the following topics:
Overview of Methods Reference
In addition to the methods that this chapter describes, you can also reference the following items in Siebel eScript. For detailed information, see the Siebel eScript quick reference chapter in Siebel Object Interfaces Reference
Applet object
Application object
Business component object
Business service object
Property set
Usage of the Term Put
The term put means to replace existing data. For example, if you put eight bytes of data to a BLOB object starting at offset 0, then Siebel CRM replaces data that currently resides in bytes 0 through 7 of the BLOB object with the input data. This book uses this definition of put throughout this chapter.
Array Methods
This topic includes the following topics:
Overview of Array Methods
Note the following:
An array is a class of object that holds multiple values instead of one value. To reference a single value in an array, you use an array index number or string that is associated with this value.
An array element is the value of an array object. It can include any data type. Siebel CRM does not require that the elements in an array be the same type, and it does not limit the number of elements that an array can include.
The index number is a number or a string that identifies the array element. This number follows the array name and you place it in square brackets.
The following example statements store values in an array:
var array = new Array; array[0] = "fish"; array[1] = "fowl"; array["joe"] = new Rectangle(3,4); array[foo] = "creeping things" array[goo + 1] = "and so on."
Array elements can be noncontiguous. For example, an array can include the following items:
An element at index 0
No element at index 1
An element at index 2
An array typically starts at index 0. It does not typically start at index 1.
Example of Using an Array
An array can use a number as an index, so it allows you to work with sequential data. For example, to keep track of how many jelly beans you eat each day, you can graph your jelly bean consumption at the end of the month. An array provides a solution for storing such data. For example:
var April = new Array; April[1] = 233; April[2] = 344; April[3] = 155; April[4] = 32;
In this example, one variable contains all the data. You can write code that examines the value of April[x] to determine how many jelly beans you ate on day x. For example:
for(var x = 1; x < 32; x++)
TheApplication().Trace("On April " + x + " I ate " + April[x] +
" jellybeans.\n");
About Array Functions
You use the following operator and an array function to create an array:
new
The following table describes different ways that you can use the array function.
| Example Array Function | Description |
|---|---|
var a = new Array();an |
This code initializes the following variable as an array with no elements: a The parentheses are optional. |
var b = new Array(31); |
This code creates an array that includes 31 array elements. If you must create an array that includes a predefined number of array elements, then you can use the number of elements as a argument of the Array function when you declare the array. |
var c = new Array(5, 4, 3, 2, 1, "blast off"); |
This code creates an array that includes six elements:
The first element of the array is c[0]. It is not c[1]. You can write code that passes elements to the Array function, which creates an array that contains the arguments that your code passes. |
You can write code that creates an array dynamically. If you write code that uses an index in brackets to reference a variable, then the variable becomes an array. If you use this technique to create an array, then you cannot use the methods and properties with an associative array.
About Associative Arrays
An associative array is a type of array that uses a string as an index element. This capability is useful if you must associate a value with a specific name. For example, you can create a month array where the elements are the names of the months and the values are the number of days in the month.
You use a string as an index to reference items in an associative array. For example:
array_name["color"] = "red"; array_name["size"] = 15;
The associative array is the only type of array that you can use with the following type of statement:
for in
This statement loops through every element in an associative array or object, regardless of how many elements it contains. For more information, see For In Statement.
Siebel CRM uses a hash table to implement the associative array, so the elements are not in an order that an indexed array uses, and you cannot use array methods with an associative array, such as split, join, or length.
Example of Using an Associative Array
The following example creates an associative array of months and days, and totals the number of days:
// open file
var fp = Clib.fopen("c:\\months.log", "at");
// populate associative array
var months = new Array();
months["November"] = 30;
months["December"] = 31;
months["January"] = 31;
months["February"] = 28;
// iterate through array items
var x;
var total = 0;
for (x in months)
{
// write array items name and value to file
Clib.fputs(x + " = " + months[x] + "\n",fp);
// Add this month’s value to the total
total = total + months[x];
}
Clib.fputs ("Total = " + total + "\n",fp);
//close file
Clib.fclose(fp);
The following is the output from this example:
November = 30 December = 31 January = 31 February = 28 Total = 120
Add Array Elements Method
The Add Array Elements method adds the elements that you define in the element argument to the end of the array. It adds these elements in the order that you define these arguments.
Format
arrayName.push([element1,element2, ..., elementn])
The following table describes the arguments for the Add Array Elements method.
| Argument | Description |
|---|---|
element1, element2, . . . elementn |
A list of elements to add to the array. |
Example
The following example includes the Add Array Elements method:
var a = new Array(1,2); TheApplication().RaiseErrorText(a.push(5,6) + " " + a); // Displays 4 1,2,5,6, the length and the new array.
Concatenate Array Method
The Concatenate Array method concatenates all the elements of an array into a string. It returns a concatenated string that includes individual array element values that are separated by commas. It does not include any input arguments.
Format
concat() toLocaleString()
The toLocaleString statement works just like the concat statement but it converts the string to another language according to the locale setting.
Example
The following example includes the Concatenate Array method:
var v = new Array; v[0] = 7; v[1] = 3; v.concat(); // The result would be "7,3"
Create Array Elements Method
The Create Array Elements method creates a string of array elements. It returns a string that contains the array elements. A comma or the separatorString argument separates each element.
Format
arrayName.join([separatorString])
The following table describes the arguments for the Create Array Elements method.
| Argument | Description |
|---|---|
separatorString |
A string of characters that occur between consecutive elements of the array. If you do not use a separatorString argument, then you can use a comma. |
Usage
Commas separate the array elements by default. The following example sets the value that the string variable contains to 3,5,6,3:
var a = new Array(3, 5, 6, 3); var string = a.join();
To separate the array elements, you can write code that passes another string as an optional argument to the Create Array Elements method.
Example
The following example creates a string that contains a value of 3*/*5*/*6*/*3:
var a = new Array(3, 5, 6, 3);
var string = a.join("*/*");
Delete Last Array Element Method
The Delete Last Array Element method does the following work:
Gets the length of the current Array object.
If the length is defined or is not 0, then it does the following:
Returns the last element.
Deletes the last element.
Decreases the length of the current array object by one.
If the length is undefined or is 0, then it returns an undefined value.
The Delete Last Array Element method works on the end of an array. You must use the Array Shift method to work on the beginning of an array.
Format
arrayName.pop()
Example
The following example includes the Delete Last Array Element method:
var a = new Array( "four" );
TheApplication().RaiseErrorText("First pop: " + a.pop() + ", Second pop: " +
a.pop());
// First displays the last (and only) element, the string "four".
// Then displays "undefined" because the array is empty after
// the first call removes the only element.
Get Largest Array Index Method
The Get Largest Array Index method returns the number of the highest index that the array contains, plus 1. This return value does not necessarily include the actual number of elements in an array because Siebel eScript does not require elements to be contiguous.
Format
arrayName.length
The following example includes two arrays:
var ant = new Array; var bee = new Array; ant[0] = 3 bee[0] = 88 ant[1] = 4 bee[3] = 99 ant[2] = 5 ant[3] = 6
The length property of ant and bee is equal to 4 even though ant includes twice as many array elements as bee. To remove array elements, you can write code that modifies the value of the length property. For example, if you write code that modifies ant.length to 2, then ant loses any elements that occur after the first two elements, and Siebel CRM loses the values that it stored at the other indices. If you set bee.length to 2, then bee includes the following elements:
bee[0], with a value of 88
bee[1], with an undefined value
Get Subarray Method
The Get Subarray method gets the array elements that exist in a range starting with the value that the first element argument identifies and ending with the value that the last element argument identifies. It returns a new array.
Format
slice (first element, last element)
The following table describes the arguments for the Get Subarray method.
| Argument | Description |
|---|---|
first element |
The first element that this method returns. |
last element |
The last element minus one that this method returns. |
Example
The following example includes the Get Subarray method:
var v = new Array; var u; v[0] = 7; v[1] = 3; v[2] = 4; v[3] = 5; u = v.slice ( 1, 3); // u creates new array containing v[1] and v[2] values. For example, u[0] = 3, u[1] = 4. v.shift(); // Now v[0] is 3, v[1] is 4
Insert Array Elements Method
The Insert Array Elements method inserts array elements into an array. It returns an array that includes the elements that it removed from the original array. It does the following work:
Beginning at the value that the start argument specifies, it deletes the number of array elements that the deleteCount argument specifies.
Inserts these deleted elements into the newly created return array in the same order that it uses to delete them.
To make room for new elements, it adjusts the elements in the current array object.
Inserts the array elements that you specify in the element1, element2, . . . elementn argument. It inserts these elements sequentially in the space that it creates in step 3.
Format
arrayName.splice(start, deleteCount[, element1, element2, . . . elementn])
The following table describes the arguments for the Insert Array Elements method.
| Argument | Description |
|---|---|
start |
Identifies the index where this method inserts the new array elements. This method does the following:
start = -1
|
deleteCount |
Identifies the number of array elements to remove from the array. If deleteCount is larger than the number of elements that exist in the array, then this method removes all of the elements. |
element1, element2, . . . elementn |
A list of elements that this method inserts in the array. |
Example
The following example includes the Insert Array Elements method:
var a = new Array( 1, 2, 3, 4, 5 ); TheApplication().RaiseErrorText(a.splice(1,3,6,7) + " " + a); // Displays 2,3,4 1,6,7,5 // Beginning at element in position 1, three elements (a[1], a[2], a[3] = 2,3,4) // are replaced with 6,7.
Reverse Array Order Method
The Reverse Array Order method reverses the order of the array elements so that the last element becomes the first element. It returns the elements in reverse order. It returns this reverse order in the arrayName argument. It reverses the existing array. It does not return a new array.
Format
arrayName.reverse()
The following example includes the Reverse Array Order method:
var communalInsect = new Array; communalInsect[0] = "ant"; communalInsect[1] = "bee"; communalInsect[2] = "wasp"; communalInsect.reverse();
This example produces the following array:
communalInsect[0] == "wasp" communalInsect[1] == "bee" communalInsect[2] == "ant"
Shift Array Left Method
The Shift Array Left method shifts all array elements by one position back. The first element is lost. It returns the modified array. It does not include any input arguments.
Format
shift()
The following example includes the Shift Array Left method:
var v = new Array; v[0] = 7; v[1] = 3; v[2] = 4; v[3] = 11; v.shift(); // now v[0] becomes 3, v[1] becomes 4, v[2] becomes 11
Shift Array Right Method
The Shift Array Right method shifts array elements one position forward. Siebel eScript assigns the argument values sequentially starting from the first element in the array. It fills the remaining array elements with values from the original array starting with the first value.
Format
unshift (integer)
You can include any number of arguments.
Example
The following example includes the Shift Array Right method:
var v = new Array; v[0] = 7; v[1] = 3; v[2] = 4; v[3] = 5; v.unshift (11, 12); // v[0] is 11 now, v[1] is 12, v[2] is 7 , v[3] is 3
Sort Array Method
The Sort Array method sorts array elements into an order that you specify. It returns the sorted array elements.
Format
arrayName.sort([compareFunction])
The following table describes the arguments for the Sort Array method.
| Argument | Description |
|---|---|
compareFunction |
Specifies the sort order. This method does the sort differently depending on if you include the compareFunction argument:
|
Example
The following example uses the Sort Array method with and without a compare function:
function compareNumbers(a, b)
{
return a - b;
}
var a = new Array(5, 3, 2, 512);
var fp = Clib.fopen("C:\\log\\Trace.log", "a");
Clib.fprintf(fp, "Before sort: " + a.join() + "\n");
a.sort(compareNumbers);
Clib.fprintf(fp, "After sort: " + a.join() + "\n");
Clib.fclose(fp);
This example does the following:
Displays the results of a sort without the function.
Uses the following function to sort the numbers:
compareNumbers(a, b)In this function, if a and b are two array elements that Siebel eScript compares, then Siebel eScript does the following:
If compareNumbers(a, b) is less than zero, then it gives b a lower index than a.
If compareNumbers(a, b) returns zero, then it does not modify the order of a and b.
If compareNumbers(a, b) is greater than zero, then it gives b a higher index than a.
String Methods
This topic describes string methods. It includes the following topics:
Overview of String Methods
The value property of a string object describes a sequence of text characters. In this topic, the term string represents the value of an instance of the string object. Other properties of the string object describe the string value and methods of the string object that manipulate the string value.
To indicate that a text literal is a string, you enclose it with quotation marks. In the following example, the first statement places the hello string in the word variable. The second statement sets the word variable to have the same value as the hello variable:
var word = "hello"; word = hello;
To declare a string you can use single quotes instead of double quotes. No difference exists between these quotes in Siebel eScript.
This topic uses the following formats:
stringVar. Indicates a string variable. To use a property or to call a method, a specific instance of a variable must precede the period.
String name. Indicates a static method of the string object. It does not apply to a specific instance of the string object.
How Siebel eScript Handles Special Characters In a String
A quotation mark is an example of a special character. To use a special character in a string, you must use a specific combination of characters that represent the special character. This combination allows Siebel CRM to understand how you intend it to use the character. For example, a quotation mark that is part of a string or a quotation mark that marks the end of the string.
The following table shows the character combinations that represent special characters. You cannot write code that uses these character combinations in a string that is enclosed by back quotes. For more information, see the following section.
| Character Combination | Special Character That the Character Combination Represents |
|---|---|
\a |
Audible bell. |
\b |
Backspace. |
\f |
Form feed. |
\n |
Newline. |
\r |
Carriage return. |
\t |
Tab. |
\v |
Vertical tab. |
\’ |
Single quote. |
\” |
Double quote. |
\\ |
Backslash character. |
\0### |
Octal number. For example: |
\x## |
Hex number. For example: |
\0 |
Null character. For example: |
\u#### |
Unicode number. For example: |
Back Quote Usage in a String
To configure Siebel eScript to not translate a character combination that typically represents a special character, you can use the following back quote:
`
If you use the back quote, then Siebel eScript interprets the character combination as a part of the string. For example, the following code lines illustrate different ways to reference a file name:
"c:\\autoexec.bat" // traditional C method 'c:\\autoexec.bat' // traditional C method `c:\autoexec.bat' // alternative Siebel eScript method
If a string includes a back quote, then you cannot include a special character that is represented by a back slash followed by a letter in that string. For example, \n.
Most versions of JavaScript do not support a string that includes a back quote. If you plan to use your script in some form of JavaScript other than Siebel eScript, then do not use back quotes.
Change String to Lowercase Method
The Change String to Lowercase method modifies every character that resides in the stringVar variable that is in uppercase to the lowercase equivalent. It returns a copy of this string that includes all lowercase characters.
Format
stringVar.toLowerCase()
The following example assigns the value e. e. cummings to the variable poet:
var poet = "E. E. Cummings"; poet = poet.toLowerCase();
Change String to Uppercase Method
The Change String to Uppercase method modifies every character that resides in the stringVar variable that is in lowercase to the uppercase equivalent. It returns a copy of this string that includes all uppercase characters.
Format
stringVar.toUpperCase()
The following example accepts a file name as input and displays it in uppercase:
var filename = "c:\\temp\\trace.txt";;
TheApplication().RaiseErrorText("The filename in uppercase is "
+filename.toUpperCase());
Create String From Substring Method
The Create String From Substring method returns a new string. Note the following:
This string includes characters that the stringVar variable contains according to the start position and the end position that you specify.
The length of this new string is equal to the value of the end argument minus the value of the start argument.
It does not return the character that resides at the end position. If you do not specify the end argument, then it returns the characters from the value you specify in the start argument to the end of the string that resides in the stringVar variable.
Format
stringVar.substring(start[, end])
The following table describes the arguments for the Create String From Substring method.
| Argument | Description |
|---|---|
start |
An integer that identifies the starting position of the string that this method returns. |
end |
An integer that identifies the ending position plus 1 of the last character of the string that this method returns. |
Example
For an example, see Replace String Method.
Create String From Unicode Values Method
The Create String From Unicode Values method converts Unicode values to a string. It uses Unicode values that you specify to determine the characters that are part of the string that it creates.
The String name is a property of the String constructor, so you use with this method instead of the variable name that you use with an instance method. Siebel eScript assumes that the values in the arguments that it passes to this method are Unicode values.
For more information, see Clib Convert Character to ASCII Method.
Format
String.fromCharCode(code1, code2, ... coden)
The following table describes the arguments for the Create String From Unicode Values method.
| Argument | Description |
|---|---|
code1, code2, ... coden |
Each argument is an integer that identifies a Unicode code number. |
Example 1
The following example sets the string1 variable to AB:
var string1 = String.fromCharCode(0x0041,0x0042);
The following example uses the decimal Unicode values of the characters to create a string:
var seblStr = String.fromCharCode(83, 105, 101, 98, 101, 108);
This example provides a string that contains the following characters:
Siebel
For another example, see Write Byte to Buffer Method.
Get Character From String Method
The Get Character From String method returns the character that resides at a specific location in a string. The length of this character is 1.
To get the first character in a string, you use position 0. For example:
var string1 = "a string"; var firstchar = string1.charAt(0);
To get the last character in a string, you use length minus 1. For example:
var lastchar = string1.charAt(string1.length - 1);
If the value in the position argument is not between 0 and the value of stringVar.length minus 1, then this method returns an empty string.
Format
stringVar.charAt(position)
The following table describes the arguments for the Get Character From String method.
| Argument | Description |
|---|---|
position |
An integer that describes the position in the string of the character that this method returns. The position of the first character in the string is 0. |
Get Unicode Character From String Method
The Get Unicode Character From String method returns the Unicode value of the character that resides at a specific position in a string. It returns a 16-bit integer between 0 and 65535. The value of the position argument identifies this position. If no character exists at this position, then it returns the following value:
NaN
This method uses the same arguments as the Get Regular Expression From String method. For more information, see Get Character From String Method. For more information, see the following topics:
Format
string Var.char CodeAt(position)
Usage
To get the first character in a string, you use position 0. For example:
var string1 = "a string"; string1.charCodeAt(0);
To get the last character in a string, you use length minus 1. For example:
string1.charCodeAt(string1.length - 1);
If the value in the position argument is not between 0 and the value of stringVar.length minus 1, then the Get Unicode Character From String method returns an empty string.
Example
The following eScript code configures Siebel CRM to allow the user to only enter characters that are part of the Latin character set. These characters must possess a Unicode value of less than 128. The user enters these characters in the First Name field. You add this code to the Contact business component. The Get Unicode Character From String method evaluates the Unicode value of each character that the user enters in the field that the FieldValue argument specifies:
function BusComp_PreSetFieldValue (FieldName, FieldValue)
{
// prevent non latin characters in First Name field
if (FieldName == "First Name")
{
for (var i=0;i<FieldValue.length;i++)
{
var co = FieldValue.charCodeAt(i);
if (co > 127)
{
TheApplication().RaiseErrorText("Only characters from latin character
set are allowed!");
}
}
}
return (ContinueOperation);
}
Get Regular Expression From String Var Method
The Get Regular Expression From StringVar method searches stringVar for a regular expression. It returns one of the following:
If it finds a match, then it returns an array of strings that includes information about each string and the property sets for these strings.
If it does not find the regular expression, then it returns the following value:
Null
Format
stringVar.match(regexp)
The following table describes the arguments for the Get Regular Expression From StringVar method.
| Argument | Description |
|---|---|
regexp |
A regular expression that you describe as a literal or as a variable. |
Usage without Setting the Global Attribute
If you use the Get Regular Expression From StringVar method with the g global attribute not set on the regular expression, then this usage is the same as with the Get Regular Expression From String method. For more information, see Get Regular Expression from String Method and Get Regular Expression from String Method.
Usage with Setting the Global Attribute
If you use the Get Regular Expression From StringVar method, and if you set the g global attribute on the regular expression, and if this method finds a match, then it does the following:
Returns element 0 of the return array as the first text in the string that matches the primary pattern of the regular expression.
Returns each subsequent element of the return array as the next text in the string that matches the primary pattern of the regular expression, and that starts after the last character of the previous match. It does not return any matches that overlap other matches.
For example, assume the following is true:
The primary pattern of the regular expression is a.. (the letter a followed by any two characters).
The string is abacadda.
In this situation the return array includes the following:
aba
add
It does not include aca.
If you set the g global attribute on the regular expression, then usage for the Get Regular Expression From StringVar method is very different than usage for the Get Regular Expression From String method.
For more information, see Get Regular Expression from String Method.
Example 1
The following example uses the Get Regular Expression From StringVar method with a regular expression whose global attribute is not set:
function fn ()
{
var myString = new String("Better internet");
var myRE = new RegExp(/(.).(.er)/i);
var results = myString.match(myRE);
var resultmsg = "";
for(var i =0; i < results.length; i++)
{
resultmsg = resultmsg + "return[" + i + "] = " + results[i] + "\n";
}
TheApplication().RaiseErrorText(resultmsg);
}
fn ();
This example provides the following output:
return[0] = etter \\First text that contains primary pattern ...er (any three
\\characters followed by "er")
return[1] = e \\First text that matches the first subpattern (.) (any single
\\character) in the first text that matches the primary pattern
return[2] = ter \\First text that matches the second subpattern (.er) (any single
\\character followed by "er") in the first text that matches
\\the primary pattern
The following example uses the Get Regular Expression From StringVar method with a regular expression whose global attribute is set. The method returns matches of the primary pattern of the regular expression that do not overlap:
function fn ()
{
var str = "ttttot tto";
var pat = new RegExp("t.t", "g");
var rtn = str.match(pat);
var resultmsg = "";
for(var i =0; i < rtn.length; i++)
{
resultmsg = resultmsg + "match [" + i + "] = " + rtn[i] + "\n";
TheApplication().RaiseErrorText(resultmsg);
}
}
fn ();
This code produces the following output. This output does not include the ttt instance that starts at position 1 or the t t instance because these instances start in other strings that the Get Regular Expression From StringVar method returns:
match [0] = ttt match [1] = tot
Get String Length Method
The Get String Length method returns an integer that describes the length of the string.
Format
stringVar.length
The following example displays the number 14, which is the number of characters in the string. The position of the last character in the string is equivalent to the value in stringVar.length minus 1, because the position begins at 0, not at 1:
var string1 = "No, thank you."; TheApplication().RaiseErrorText(string1.length);
The following example returns the length of a name that the user enters, including spaces:
var userName = "Christopher J. Smith"; TheApplication().RaiseErrorText( "Your name has " + userName.length + " characters.");
Parse String Method
The Parse String method parses a string into an array of strings according to the delimiters that you specify in the delimiter argument. Note the following:
It returns an array of strings, each of which begins at an instance of the delimiter character.
It does not include the delimiter in any of the strings.
If you do not specify the delimiter argument or if this argument contains an empty string (""), then it returns an array of one element, which includes the original string.
It is the inverse of arrayVar.join.
For more information, see Create Array Elements Method.
Format
stringVar.split([delimiter])
The following table describes the arguments for the Parse String method.
| Argument | Description |
|---|---|
delimiter |
The character where this method splits the value stored in stringVar. |
Example
The following example splits a typical Siebel command line into separate elements. It creates a separate array element at each space character. You must configure Siebel CRM to modify the string with character combinations so that Siebel eScript can understand it. The cmdLine variable must occur on a single line. In this book this variable wraps to a second line:
function Button3_Click ()
{
var msgText = "The following items occur in the array:\n\n";
var cmdLine = "C:\\Siebel\\bin\\siebel.exe /c
\'c:\\siebel\\bin\\siebel.cfg\' /u SADMIN /p SADMIN /d Sample"
var cmdArray = cmdLine.split(" ");
for (var i = 0; i < cmdArray.length; i++)
msgText = msgText + cmdArray[i] + "\n";
TheApplication().RaiseErrorText(msgText);
}
This example produces the following result:
The following items occur in the array: C:\Siebel\bin\siebel.exe /c 'C:\siebel\bin\siebel.cfg' /u SADMIN /p SADMIN /d Sample
Replace String Method
The Replace String method uses the regular expression that you define in the pattern argument to search a string. If it finds a match, then it replaces the string it finds with the string that you define in the replexp argument.
If you use T eScript code, and if this method replaces a string, then it sets the appropriate static properties for the regular expression object. These properties provide more information about the replacements. For more information, see Get Regular Expression from String Method.
Format
stringVar.replace(pattern, replexp)
The following table describes the arguments for the Replace String method.
| Argument | Description |
|---|---|
pattern |
Regular expression that this method finds in a string. |
replexp |
A replacement expression that can include one of the following items:
|
Special Characters You Can Use in a Replacement Expression
The following table describes the special characters that you can use in a replacement expression.
| Character | Description |
|---|---|
$1, $2 … $9 |
The text that the regular expression matches. This text resides in a set of parentheses in the string. For example, $1 replaces the text that the Replace String method matches in the first regular expression it encounters that resides in a set of parentheses. |
$+ |
Same as the $1, $2 … $9 characters, except with the $+ character the replacement occurs in the regular expression that resides in the last set of parentheses. |
$& |
The text that a regular expression matches. |
$` |
The text that precedes the text that a regular expression matches. |
$' |
The text that comes after the text that a regular expression matches. |
\$ |
The dollar sign character. |
Example
The following example includes the Replace String method:
var rtn;
var str = "one two three two one";
var pat = /(two)/g;
// rtn == "one zzz three zzz one"
rtn = str.replace(pat, "zzz");
// rtn == "one twozzz three twozzz one";
rtn = str.replace(pat, "$1zzz");
// rtn == "one 5 three 5 one"
rtn = str.replace(pat, five());
// rtn == "one twotwo three twotwo one";
rtn = str.replace(pat, "$&$&”);
function five() {
return 5;
}
Search String for Substring Method
The Search String for Substring method searches the stringVar variable for the entire string that you specify in the substring argument. It returns the position of the first occurrence of this string.
If any of the following situations is true, then it returns a value of negative 1:
It does not find the value that you specify in the substring argument.
The value you specify in the offset argument is outside the range of positions in the string.
Values you enter for arguments are case-sensitive.
Format
stringVar.indexOf(substring [, offset])
The following table describes the arguments for the Search String for Substring method.
| Argument | Description |
|---|---|
substring |
One or more characters that this method searchs.The substring argument can contain a single character. |
offset |
The position in the string where this method starts searching. This method does the following according to how you set the offset argument:
|
Example 1
The following example returns the position of the first a character that occurs in the string. In this example, the first a character occurs at position 2:
var string = "what a string";
var firsta = string.indexOf("a")
The following example returns 3, which is the position of the first a character in the string when starting from the second character of the string:
var magicWord = "abracadabra";
var secondA = magicWord.indexOf("a", 1);
For more information, see the following topics:
Search String for Last Substring Method
The Search String for Last Substring method searches the stringVar variable for the string that you specify in the substring argument. It returns the position of the last occurrence of this string in a string.
If any of the following situations is true, then it returns a value of negative 1:
It does not find the value that you specify in the substring argument.
The value you specify in the offset argument is outside the range of positions in the string.
Note the following:
To limit the search to a string of leftmost characters of the string, you can use the offset argument.
The first character of the substring must occur at a position that is no greater than the offset.
If the value you specify in the substring argument does not occur entirely before or at the offset, then the Search String for Last Substring method still returns the position of the substring that it finds.
This method uses the same arguments as the Search String for Substring method. For more information, see Search String for Substring Method.
Format
stringVar.lastIndexOf(substring [, offset])
This method does the following according to how you specify the offset argument:
You do specify the offset argument. It searches the string up to the position that you specify in the offset argument, and then returns the rightmost position where the substring begins. It does not consider any substring that occurs after the position that you specify in the offset argument.
You do not specify the offset argument. It returns the rightmost position in the entire string where the substring begins.
Example 1
The following example returns the position of the last occurrence of the a character in the string. It returns a value of 5:
var string = "what a string";
string.lastIndexOf("a")
The following example returns the position of the last occurrence of the abr string, beginning at a position that is not greater than 8. It returns a value of 7:
var magicWord = "abracadabra";
var lastabr = magicWord.lastIndexOf("abr", 8);
Search StringVar for Regular Expression Method
The Search StringVar for Regular Expression method searches a string for a regular expression. It returns one of the following:
If it finds the regular expression, then it returns the position of this regular expression.
If it does not find the regular expression, then it returns negative 1.
You can write code that runs this method in server script or browser script.
This method uses the same argument as the Get Regular Expression From StringVar method. For more information, see Get Regular Expression From String Var Method.
Format
stringVar.search(regexp)
The following example uses the Search StringVar for Regular Expression method:
function Test(sValue)
{
//Validate for 5 digit numbers
var sCheck = /^\d{5}$/; //regular expression defining a 5 digit number
if(sValue.search(sCheck)==0)
{
return("Valid");
}
else
{
return("Invalid");
}
}
BLOB Methods
This topic includes the following topics:
About the blobDescriptor
The blobDescriptor object describes the structure of a BLOB (binary large object). If you must configure Siebel CRM to send an object to a process other than the Siebel eScript interpreter, such as to a Windows API function, then you must configure it to create a blobDescriptor object that describes the order and type of data of this object. This description describes how to store the properties of the object in memory. You use it with methods such as the Siebel Library Call DLL method or the Clib Read From File method. For more information, see Siebel Library Call DLL Method and Clib Read From File Method.
A BLOB descriptor includes the same data properties as the object it describes. You must set a value for each property that specifies how much memory is required to store the data that the property holds. To refer to the arguments passed to the constructor function, you use the following keyword:
this
You can think of this keyword conceptually as this object. Consider the following object:
Rectangle(width, height)
{
this.width = width;
this.height = height;
}
To configure Siebel eScript to pass data to the following items, you typically use a BLOB descriptor:
Siebel eScript data structure, which is similar to JavaScript
C program or a C++ program
Clib method
These items expect a rigid and precise description of the values that Siebel eScript passes.
Example of Using a blobDescriptor
The following example creates a blobDescriptor object that describes the Rectangle object:
var bd = new blobDescriptor(); bd.width = UWORD32; bd.height = UWORD32;
In this example, you can use Siebel eScript to pass the bd variable as a blobDescriptor argument to a function that requires a blob descriptor. The values set for the properties depend on what the receiving function expects. In this example the function that Siebel CRM calls expects to receive an object that includes two 32-bit words or data values. If you write a BLOB descriptor for a function that expects to receive an object that contains two 16-bit words, then set the value for the two properties to UWORD16.
Values You Must Use with a blobDescriptor
The following table describes the values that you must use with blobDescriptor object properties. To indicate the number of bytes that are required to store the property, you use one of these values. If the BLOB descriptor describes an object property that is a string, then you must set the corresponding property to a numeric value that is larger than the length of the longest string that the property can hold. You can write code that omits an object method from a BLOB descriptor.
| Value | Description |
|---|---|
WCHAR |
Handled as a native Unicode string. |
UWORD8 |
Stored as an unsigned byte. |
SWORD8 |
Stored as an integer. |
UWORD16 |
Stored as an unsigned 16-bit integer. |
SWORD16 |
Stored as a signed 16-bit integer. |
UWORD24 |
Stored as an unsigned 24-bit integer. |
SWORD24 |
Stored as a signed 24-bit integer. |
UWORD32 |
Stored as an unsigned 32-bit integer. |
SWORD32 |
Stored as a signed 32-bit integer. |
FLOAT32 |
Stored as a floating-point number. |
FLOAT64 |
Stored as a double-precision floating-point number. |
STRINGHOLDER |
Indicates a value that Siebel eScript saves in a string. Siebel eScript passes this value to a function. This function saves this string. Siebel eScript does the following work:
|
Get BLOB Data Method
This Get BLOB Data method reads data from a binary large object. It returns the data from the BLOB.
Format A
Blob.get(blobVar, offset, dataType)
You use format A for byte, integer, or float data.
Format B
Blob.get(blobVar, offset, bufferLen)
You use format B for byte data.
Format C
Blob.get(blobVar, offset, blobDescriptor dataDefinition)
You use format C for object data.
Arguments
The following table describes the arguments for the Get BLOB Data method.
| Argument | Description |
|---|---|
blobVar |
The name of the binary large object that this method manipulates. |
offset |
The position in the BLOB that Siebel CRM uses to read the data. |
dataType |
An integer value that identifies the data format in the BLOB. The dataType argument must include one of the values you must use with a BLOB descriptor. For more information, see Values You Must Use with a blobDescriptor. |
bufferLen |
An integer that specifies the size of the buffer in bytes. |
blobDescriptor dataDefinition |
A blobDescriptor object that identifies the data format in the BLOB. |
Example
The following example describes how to get values from a BLOB object:
function GetBlobVal()
{
var a, b, c;
a = "";
b = 1234;
c = 12345678;
// Call a function to build the Blob
var blob = BuildBlob(a, b, c);
TheApplication().TraceOn("c:\\temp\\blob.txt","Allocation","All");
// Get the values from the blob object
// The first variable is string
var resultA = Blob.get(blob,0,1000);
// The second variable is an integer
var resultB = Blob.get(blob,1000,UWORD16);
// The third variable has a type of float
var resultC = Blob.get(blob,1002,FLOAT64);
TheApplication().Trace(resultA);
TheApplication().Trace(resultB);
TheApplication().Trace(resultC);
}
function BuildBlob(a, b, c)
{
var blob;
a = "Blob Test Value From Function";
var offset = Blob.put(blob, 0, a, 1000);
offset = Blob.put(blob, offset, b*2, UWORD16);
Blob.put(blob, offset, c*2, FLOAT64);
return blob;
}
Get BLOB Size Method
The Get BLOB Size method determines the size of a BLOB object. It returns the number of bytes that this BLOB object contains. It returns this value in the blobVar argument.
Format A
// Format A Blob.size(blobVar[, SetSize]) // Format B Blob.size(dataType) // Format C Blob.size(bufferLen) // Format D Blob.size(blobDescriptor dataDefinition)
The following table describes the arguments for the Get BLOB Size method. If you specify any of the following arguments, then Siebel CRM uses the values you specify to convert Siebel eScript data to a BLOB, and to covert BLOB data to Siebel eScript data:
dataType
bufferLen
dataDefinition
| Argument | Description |
|---|---|
blobVar |
The name of the binary large object that this method examines. |
setSize |
An integer that determines the size of the BLOB. If you specify the SetSize argument, then this method does the following work:
|
dataType |
An integer value that describes the format of the data in the BLOB. The dataType argument must include one of the values that you use with a BLOB descriptor. For more information, see Values You Must Use with a blobDescriptor. |
bufferLen |
An integer that describes the number of bytes in the buffer. |
blobDescriptor dataDefinition |
A blobDescriptor object that describes the format of the data in the BLOB. |
Write BLOB Data Method
The Write BLOB Data method writes data to a binary large object. It returns an integer that identifies the byte offset of the byte that occurs after the end of the data that this method writes. If it writes data at the end of the BLOB, then this integer identifies the size of the BLOB.
You can write code that adds data at any position in a BLOB. The data length is variable. This method does not pad each data element with null values as a way to make every data element a uniform length. The exact length depends on the CPU. Thirty two bytes is a common length.
For more information, see Usage of the Term Put.
Format A
// Format A Blob.put(blobVar[, offset], data, dataType) // Format B Blob.put(blobVar[, offset], buffer, bufferLen) // Format C Blob.put(blobVar[, offset], srcStruct, blobDescriptor dataDefinition)
To pass the contents of an existing BLOB that resides in the srcStruct argument to the blobVar argument, you can use format C.
Arguments
The following table describes the arguments for the Write BLOB Data method.
| Argument | Description |
|---|---|
blobVar |
The name of the binary large object that this method manipulates. |
offset |
The position in the BLOB where this method adds data. If you do not provide a value for the offset argument, then this method does one of the following depending on if the BLOB is defined:
|
data |
The data that this method writes. |
dataType |
The format of the data in the BLOB. This method converts the data to the format that you specify in the dataType argument, and then copies this data to the position that you specify in the offset argument. If the value that you specify in the dataType argument is not the length of a byte buffer, then the dataType argument must include one of the values you use with a BLOB descriptor. For more information, see Values You Must Use with a blobDescriptor. |
buffer |
A variable that contains a buffer. |
bufferLen |
An integer that specifies the buffer length. |
srcStruct |
A BLOB that contains the data that this method writes. |
blobDescriptor dataDefinition |
A blobDescriptor object that describes the format of the data in the BLOB. |
Example
Assume you send a data pointer to an external C library. Assume the library expects data in the following packed C structure:
struct foo
{
signed char a;
unsigned int b;
double c;
};
The following example creates a structure from three corresponding variables and returns the offset of the next available byte:
function BuildFooBlob(a, b, c)
{
var offset = Blob.put(foo, 0, a, SWORD8);
offset = Blob.put(foo, offset, b, UWORD16);
Blob.put(foo, offset, c, FLOAT64);
return foo;
}
The following example creates a structure from three corresponding variables but does not include an offset:
functionBuildFooBlob(a, b, c)
{
Blob.put(foo, a, SWORD8);
Blob.put(foo, b, UWORD16);
Blob.put(foo, c, FLOAT64);
return foo;
}
Buffer Methods
This topic describes buffer methods. It includes the following topics:
Overview of Buffer Methods
A buffer method allows you to manipulate data at a very basic level. It is required if the relative position of data in memory is important. You can configure Siebel CRM to store any type of data in a buffer object.
You can configure Siebel CRM to create a new buffer object from the following items:
Nothing.
A string, a buffer, or a buffer object. Siebel CRM copies the contents of the string, buffer, or buffer object to the new buffer object.
The examples for buffer methods in this chapter use the bufferVar argument as a generic argument name. Siebel CRM assigns a buffer object to this generic argument.
About Buffer Constructors
This topic describes the formats you can use to create a buffer object.
The following table describes the buffer constructor arguments that are common to formats A, B, C, and D.
| Argument | Description |
|---|---|
unicode |
You can use one of the following values:
|
bigEndian |
You can use one of the following values:
|
Format A
new Buffer([size] [, unicode] [, bigEndian]);
The following table describes the buffer constructor arguments that are specific to format A.
| Argument | Description |
|---|---|
size |
The size of the new buffer that Siebel eScript creates. You can do one of the following:
|
Format B
new Buffer( string [, unicode] [, bigEndian] );
Format B creates a new buffer object from a string that you provide. A line of code that uses format B creates a new buffer object from the buffer provided. Siebel CRM copies the contents of the buffer into the new buffer object. The unicode argument and the bigEndian argument do not affect this conversion, although they do set the relevant flags for future use.
The following table describes the buffer constructor arguments that are specific to format B.
| Argument | Description |
|---|---|
string |
The string that Siebel eScript uses as input to create the buffer. If the string argument contains a Unicode string, then Siebel eScript creates the buffer as a Unicode string. To use a Unicode string, you must enable Unicode in the Siebel application. To override this behavior, you can specify false in the optional unicode argument. The size of the buffer depends on if the string is a Unicode string:
A buffer constructor does not add a terminating null byte at the end of the string. |
Format C
new Buffer(buffer [, unicode] [, bigEndian]);
The following table describes the buffer constructor arguments that are specific to format C.
| Argument | Description |
|---|---|
buffer |
The buffer that Siebel eScript uses as input to create the new buffer. |
Format D
new Buffer(bufferobject);
A line of code that uses format D creates a new buffer object from another buffer object. Siebel CRM copies the contents of the buffer object to the new buffer verbatim, including the cursor position, size, and data.
The following table describes the buffer constructor arguments that are specific to format D.
| Argument | Description |
|---|---|
bufferobject |
The buffer object that Siebel eScript uses as input to create the new buffer. |
Example
The following example creates new buffer objects:
function BufferConstruct()
{
TheApplication().TraceOn("c:\\temp\\BufferTrace.doc","Allocation","All");
// Create empty buffer with size 100
var buff1 = new Buffer(100 , true , true);
// Create a buffer from string
var buff2 = new Buffer("This is a buffer String constructor example", true);
// Create buffer from buffer
var buff3 = new Buffer(buff2,false);
try
{
with(buff1)
{
// Add values from 0-99 to the buffer
for(var i=0;i<size;i++)
{
putValue(i);
}
var val = "";
cursor=0;
// Read the buffer values into variable
for(var i=0;i<size;i++)
{
val += getValue(1)+" ";
}
// Trace the buffer value
TheApplication().Trace("Buffer 1 value: "+val);
}
with(buff2)
{
// Trace buffer 2
TheApplication().Trace("Buffer 2 value: "+getString());
}
// Trace buffer 3
with(buff3)
{
TheApplication().Trace("Buffer 3 value: "+getString());
}
}
catch(e)
{
TheApplication().Trace(e.toString());
}
}
Create Buffer Method
The Create Buffer method extracts the data that exists between two positions in a buffer. It returns this data in a new buffer object. This method does the following:
If the value that the beginning argument contains is less than 0, then it treats this value as 0, which is the beginning of the buffer.
If the value that the end argument contains is beyond the end of the buffer, then it uses null bytes to increase the size of the new buffer. It does not modify the source buffer. It duplicates the values of the unicode argument and the bigEndian argument in the new buffer.
Sets the length of the new buffer to the value that the end argument contains minus the value that the beginning argument contains.
Format
bufferVar.subBuffer(beginning, end)
The following table describes the arguments for the Create Buffer method.
| Argument | Description |
|---|---|
beginning |
The position in the source buffer where this method begins to extract data. |
end |
The position in the source buffer where this method stops extracting data. |
How the Create Buffer Method Sets the Cursor
The following table describes how the Create Buffer method sets the cursor.
| Original Cursor Position | How the Create Buffer Method Sets the Cursor |
|---|---|
Between the value that the beginning argument contains and the value that the end argument contains. |
Sets the cursor position to a new relative position in the new buffer. |
Before the value that the beginning argument contains. |
Sets the cursor position to 0 in the new buffer. |
After the value that the end argument contains. |
Sets the cursor position to the end of the new buffer. |
Example
The following example creates a new buffer named language and displays the contents of this buffer in a string named Siebel eScript. The Siebel eScript text begins in the nineteenth position:
var loveIt= new Buffer("I love coding with Siebel eScript!");
var language = loveIt.subBuffer(19, (loveIt.size - 1))
TheApplication().RaiseErrorText(language);
For more information, see Get String From Buffer Method.
Get Buffer Data Method
The Get Buffer Data method returns a string that contains the same data that the buffer contains. If necessary, it does a Unicode conversion according to the value of the Use Unicode in Buffer property. For more information, see Throw Statement.
Format
bufferVar.toString()
The following example uses the Get Buffer Data method:
try
{
do_something;
}
catch( e )
{
TheApplication().RaiseErrorText(Clib.rsprintf(
"Something bad happened: %s\n",e.toString()));
}
Get Cursor Position Value From Buffer Method
The Get Cursor Position Value From Buffer method returns the value that a position contains from a buffer. This position is the position where the cursor currently resides. To determine where to read from the buffer, you can use the Cursor property. For more information, see Cursor Position in Buffer Property.
Format
bufferVar.getValue([valueSize][, valueType ])
The following table describes the arguments for the Get Cursor Position Value From Buffer method.
| Argument | Description |
|---|---|
valueSize |
A positive number that describes the number of bytes that the this method reads. You can use any of the following values:
The default value is 1. These values must not conflict with any values you use with the valueType argument. For more information, see the following section. |
valueType |
The type of data that the this method reads. You can use one of the following values:
Signed is the default value. |
Values You Can Use with the ValueSize and ValueType Arguments
The following table describes the value combinations you can use with the valueSize argument and the valueType argument. The values of the valueSize argument and the valueType argument must match the structure of the data that the Get Cursor Position Value From Buffer method reads. Any other combination causes an error.
| Value in the valueSize Argument | Value in the valueType Argument |
|---|---|
1 |
signed, unsigned |
2 |
signed, unsigned |
3 |
signed, unsigned |
4 |
signed, unsigned, float |
8 |
float |
Get String From Buffer Method
The Get String From Buffer method returns a string that starts at the current cursor position in a buffer and continues for the number of bytes that you specify in the length argument. It reads the string according to the value of the unicode flag of the buffer. It does not add a terminating null byte even if you do not provide a length argument.
Format
bufferVar.getString( [length] )
The following table describes the arguments for the Get String From Buffer method.
| Argument | Description |
|---|---|
length |
The length of the string to return, in bytes. If you do not specify the length argument, then this method reads the data until it encounters one of the following items:
|
Put String in Buffer Method
The Put String in Buffer method replaces existing data in a buffer with a string that you specify. It replaces data starting at the current position of the cursor. This method does one of the following depending on if the Unicode flag in the buffer object is set:
Set. It puts the string in the buffer object as a Unicode string. It increments the cursor by twice the length of the string.
Not set. It puts the string in the buffer object as an ASCII string. It increments the cursor by the length of the string.
This method does not add a terminating null byte at end of the string.
To put a null string in the buffer object, you can use the following code:
buf1.putString("Hello"); // Put the string into the buffer
buf1.putValue( 0 ); // Add terminating null byte
Format
bufferVar.putString(string)
The following table describes the arguments for the Put String in Buffer method.
| Argument | Description |
|---|---|
string |
The string literal that this method puts in the buffer object, or the string variable whose value it puts in the buffer object. |
Example
The following example places the language string in the exclamation buffer and displays the modified contents of the explanation buffer:
function eScript_Click ()
{
var exclamation = new Buffer("I enjoy coding with . . .");
var language = "Siebel eScript.";
exclamation.cursor = 20;
exclamation.putString(language);
TheApplication().RaiseErrorText(exclamation);
}
This modification is a string that contains the following value:
I enjoy coding with Siebel eScript.
Related Topics
For more information, see the following topics:
Put Value in Buffer Method
The Put Value in Buffer method replaces existing data in a buffer with a value that you specify. It replaces data starting at the current position of the cursor. It puts the value that the buffer contains at the current cursor position, and then automatically increments the cursor value by the value that the value argument contains.
To put a value at a specific position and preserve the cursor position, you can add code that is similar to the following:
var oldCursor = bufferItem.cursor; // Save the cursor position bufferItem.cursor = 20; // Set to new position bufferItem.putValue(foo); // Put bufferItem at offset 20 bufferItem.cursor = oldCursor // Restore cursor position
For more information, see Usage of the Term Put.
Format
bufferVar.putValue(value[, valueSize][, valueType ])
The following table describes the arguments for the Put Value in Buffer method.
| Argument | Description |
|---|---|
value |
A number. |
valueSize |
The description for the valueSize argument and the valueType argument for the Put Value in Buffer method is the same as the description for these arguments for the Get Cursor Position Value From Buffer method. For more information, see Get Cursor Position Value From Buffer Method. |
valueType |
Avoiding Digit Loss
To put the value in the buffer, the Put Value in Buffer method uses byte ordering according to the current value that the bigEndian argument contains. If it puts a smaller float value, such as 4, then digits are lost. It converts a value such as 1.4 to a value that is approximately 1.39999974. This conversion is insignificant and you can ignore it.
Note the following example:
bufferItem.putValue(1.4,8,"float"); bufferItem.cursor -= 4; if( bufferItem.getValue(4,"float") != 1.4 ) // This is not necessarily true due to significant digit loss.
To prevent this situation, you can set the valueSize argument to 8 instead of 4. You can use a valueSize of 4 for a floating-point value, but be aware that some digit loss might occur. This loss might not be significant enough to affect most calculations.
Write Byte to Buffer Method
The Write Byte to Buffer method writes a byte to a buffer at a position that you specify.
Format
bufferVar[offset]
The following table describes the arguments for the Write Byte to Buffer method.
| Argument | Description |
|---|---|
offset |
A number that describes a position in the buffer that the bufferVar method identifies. This method does one of the following:
Note the following:
|
Usage
The Write Byte to Buffer method is an array-like version of the Get Cursor Position Value From Buffer method and the Put Value in Buffer method except that the Write Byte to Buffer method works only with bytes. You can write code that gets or sets these values. For example, the following code sets the goo variable to the value of a byte. This byte resides in the buffer at offset position 5:
goo = foo[5]
The following code sets the value of position 5 in the foo buffer to the value that the goo variable contains:
foo[5] = goo
This code assumes the value that the goo variable contains is a single byte value.
Every get or put operation uses eight-bit signed words (SWORD8). If you must work with character values, then you must convert these values to their ANSI equivalent or Unicode equivalent.
Related Topics
For more information, see the following topics:
Buffer Size Property
The Buffer Size property is the size of the buffer object. You can write code that sets a value for the Buffer Size property. For example:
inBuffer.size = 5
Siebel CRM does the following:
If the buffer size increases beyond the current maximum size of the buffer, then it uses null bytes to fill the additional positions.
If the buffer size decreases so that the cursor position is beyond the end of the buffer, then it moves the cursor position to the end of the modified buffer.
For more information, see Cursor Position in Buffer Property.
Format
bufferVar.size
Cursor Position in Buffer Property
The Cursor Position in Buffer property stores the current position of the buffer cursor. Note the following:
The value of the cursor position is always between 0 and the value that the Buffer Size property contains.
If you use Siebel eScript to set the cursor beyond the end of a buffer, then it increases the buffer to accommodate the new position. It fills the new positions with null bytes.
If you use Siebel eScript to set the cursor to a value that is less than 0, then it places the cursor at position 0 of the buffer.
Format
bufferVar.cursor
For examples, see Get String From Buffer Method and Create Buffer Method.
Data in Buffer Property
The Data in Buffer property is a reference to the internal data of a buffer. You can write code that uses it as a temporary value to pass buffer data to a function that does not recognize a buffer object.
Format
bufferVar.data
Use Big Endian in Buffer Property
The Use Big Endian in Buffer property is a Boolean flag that specifies to use big endian byte ordering if Siebel CRM calls the Get Cursor Position Value From Buffer method or the Put Value in Buffer method. Siebel CRM stores bytes according to the following settings:
Use Big Endian in Buffer property is true. Stores the bytes in descending order of significance.
Use Big Endian in Buffer property is false. Stores the bytes in ascending order of significance.
Siebel CRM sets this value when it creates a buffer. You can configure it to modify this value at any time.
The Use Big Endian in Buffer property defaults to the state of the operating system and processor.
If a data value includes more than one byte, then the following occurs:
The byte that contains the smallest units of the value is the least significant byte.
The byte that contains the largest units of the value is the most significant byte.
Format
bufferVar.bigEndian
Use Unicode in Buffer Property
The Use Unicode in Buffer property is a Boolean flag that specifies whether to use a Unicode string when calling the Get String From Buffer method or the Put String in Buffer method. Siebel CRM sets the value for the Use Unicode property when it creates a buffer. You can configure it to modify this value. This property defaults to false.
Format
bufferVar.unicode
The following example sets the Use Unicode in Buffer property of a new buffer to true:
var aBuffer = new Buffer(); aBuffer.unicode = true;
Date and Time Methods
This topic describes date and time methods. It includes the following topics:
Overview of Date Methods
Siebel eScript provides the following ways to work with dates:
The standard date object in JavaScript.
The Clib object that implements routines from the C programming language. For more information, see C Language Library Reference
The following methods convert dates in the format of one date system to the format of the other date system:
Date.fromSystem
Date.toSystem
This chapter describes the JavaScript Date object.
To indicate the name of a variable that you create to hold a date value, this chapter uses dateVar.
Format for Calling a Date Method
To call a date method, you must precede the method name with a specific instance of a variable followed by a period. For example, assume you create a date object named aDate. To call the getDate method, you use the following format:
aDate.getDate
Siebel CRM uses a literal value to call a static method, such as Date.parse. The beginning of a static method includes the following format:
Date.
These methods are part of the date object instead of an instance of the Date object.
Caution About Using Two Digit Dates
Siebel eScript uses the ECMAScript standard for two digit dates, which might be different from the formats that other applications use, including Siebel CRM.
Values for Dates and Times
The following table describes values for months, days, hours, minutes, and seconds. Many Siebel eScript objects use these same values.
| Time Period | Description |
|---|---|
month |
A month, specified as an integer from 0 to 11. January is 0 and December is 11. |
day |
A day of the month, specified as an integer from 1 to 31. The first day of the month is 1. The last day of the month is 28, 29, 30, or 31. |
hours |
An hour, specified as an integer from 0 to 23. Midnight is 0 and 11 PM is 23. |
minutes |
A minute, specified as an integer from 0 to 59. The first minute of an hour is 0 and the last minute of an hour is 59. |
seconds |
A second, specified as an integer from 0 to 59. The first second of a minute is 0 and the last second of a minute is 59. |
millisecond |
A millisecond, specified as an integer from 0 through 999. The first millisecond is 0 and the last millisecond is 999. |
About the Date Constructor
The Date constructor instantiates a new date object. If you include an argument, then it returns a date object that includes the date according to the argument. To create a date object that Siebel CRM sets to the current date and time, you can use the new operator as you would with any object.
Format A
// Format A var dateVar = new Date; // Format B var dateVar = new Date(milliseconds); //Format C var dateVar = new Date(dateString); // Format D var dateVar = new Date(year, month, day); //Format E var dateVar = new Date(year, month, day, hours, minutes, seconds);
The following table describes arguments for the date constructor.
| Argument | Description |
|---|---|
dateString |
A string that includes a date and optional time. |
year |
A year. If the year is between 1950 and 2050, then you can include only the final two digits. Otherwise, you must include four digits. For more information, see Caution About Using Two Digit Dates. |
month |
For more information, see Values for Dates and Times. |
day |
For more information, see Values for Dates and Times. |
hours |
For more information, see Values for Dates and Times. |
minutes |
For more information, see Values for Dates and Times. |
seconds |
For more information, see Values for Dates and Times. |
milliseconds |
The number of milliseconds since January 1, 1970. |
Usage for Format B
Format B returns a date and time that includes the number of milliseconds since midnight, January 1, 1970. Using milliseconds is a standard way of including dates and times. It simplifies calculating the amount of time between one date and another. It is recommended that you configure Siebel CRM to convert a date to milliseconds before it performs a calculation on the date.
Usage for Format C
Format C accepts a string that includes a date and an optional time. The format for this string includes one or more of the following fields, in any order:
month day, year hours:minutes:seconds
For example:
"October 13, 1995 13:13:15"
This string specifies a date of October 13, 1995 and a time of one thirteen and 15 seconds PM. In a 24 hour format, this value is 13:13 hours and 15 seconds. The time specification is optional. If you include it, then the seconds specification is optional.
Siebel CRM can pass the result of the BusComp.GetFieldValue(datetime field) method to the date constructor. The GetFieldValue method always returns date fields using the following format: MM/DD/YYYY hh:mm:ss.
Siebel CRM interprets the time in a date string as local time, according to the time zone setting of the operating system. If you require Siebel CRM to interpret the time as UTC time, then you can append GMT to the date string. For example:
"07/09/2004 14:22:00 GMT"
If a business component field includes a UTC time rather than a local time, then you can append GMT to the code to configure Siebel CRM to pass is to the date constructor. For example:
var utctime = new Date(GetFieldValue("UTC Time") + " GMT");
Format for formats D and E are self-explanatory. You configure Siebel CRM to pass arguments to them as integers.
Example
The following example includes a date constructor:
var aDate = new Date(1802, 6, 23)
This example creates a date object that contains a date of July 23, 1802.
Convert Date and Time to String Method
The Convert Date and Time to String method returns a string that includes the date and time of a date object according to the time zone of the computer that runs the script. It returns this date in the following format:
Day Mon dd hh:mm:ss yyyy
If you use this code in Siebel eScript, then the code runs on the Siebel Server. The Siebel Server might or might not reside in the same time zone where the user resides. If you use this code in JavaScript, then the code runs on the user computer and uses the time zone of the user computer.
Format
dateVar.toLocaleString() dateVar.toString()
The following example displays the local time from the computer clock, the UTC time, and the Greenwich mean time (GMT):
var aDate = new Date();
var local = aDate.toLocaleString();
var universal = aDate.toUTCString();
var greenwich = aDate.toGMTString();
TheApplication().RaiseErrorText("Local date is " + local +
"\nUTC date is " + universal +
"\nGMT date is " + greenwich);
This example provides the following results:
Local date is Fri Aug 12 15:45:52 2005 UTC date is Fri Aug 12 23:45:52 2005 GMT GMT date is Fri Aug 12 23:45:52 2005 GMT
For more information, see the following topics:
Convert Date to Integer Method
The Convert Date to Integer method converts a date object to a system time format that is in the same format as the format that the Clib Convert Time to Integer method returns. To create a date object from a variable in system time format, see Get Day of Week Method.
Format
Date.toSystem()
The following example converts a date object to a system format that methods of the Clib object can use:
var Sys Date = obj Date.toSystem();
Convert Date String to Date Object Method
The Convert Date String to Date Object method converts a date string to a date object. It returns a date object that includes the date in the dateString argument.
Format
Date.parse(dateString)
The following table describes the arguments for the Convert Date String to Date Object method.
| Argument | Description |
|---|---|
dateString |
A string that uses the following format: weekday, Month dd, yyyy hh:mm:ss |
Usage
To call the Convert Date String to Date Object method, you use the date constructor rather than a variable. You must use the following format:
Friday, October 31, 1998 15:30:00 -0800
where:
The last number in the string is the offset from Greenwich mean time.
The following items use this format:
The dateVar.toGMTString method
Email applications
Internet applications
You can omit the day of the week, time zone, time specification, and seconds field. For example, consider the following code:
var aDate = Date.parse(dateString);
This code is equivalent to the following code:
var aDate = new Date(dateString);
The following example results in a value of 9098766000:
var aDate = Date.parse("Friday, October 31, 1998 15:30:00 -0220");
TheApplication().RaiseErrorText(aDate);
Convert Date to GMT String Method
The Convert Date to GMT String method converts a date object to a string according to Greenwich mean time. It returns the date that Siebel CRM sets in dateVar. It returns this date as a string in the following format:
Day Mon dd hh:mm:ss yyyy GMT.
Format
dateVar.toGMTString()
The following example accepts a number of milliseconds as input and converts it to GMT time as the number of milliseconds before or after the time on the computer clock:
function clickme_Click ()
{
var aDate = new Date;
var milli = 200000;
aDate.setUTCMilliseconds(milli);
TheApplication().RaiseErrorText(aDate.toGMTString());
}
For more information, see the following topics:
Convert Integer Date to JavaScript Date Method
The Convert Integer Date to JavaScript Date method converts a time from the format that the Clib Convert Time to Integer method returns to a standard JavaScript date object. To call the Convert Integer Date to JavaScript Date method, you use the date constructor rather than a variable.
Format
Date.fromSystem(time)
The following table describes the arguments for the Convert Integer Date to JavaScript Date method.
| Argument | Description |
|---|---|
time |
A variable that holds a system date. |
Example
The following example creates a date object from date information obtained through Clib:
var SysDate = Clib.time(); var ObjDate = Date.fromSystem(SysDate);
For more information, see the following topics:
Get Day of Month Method
The Get Day of Month method returns the day of the month of a date object. For more information, see Values for Dates and Times.
Format
dateVar.getDate()
The following example returns a value of 7, the day part of the date object:
function Button2_Click ()
{
var MyBirthdayDay = new Date("1958", "11", "7");
TheApplication().RaiseErrorText("My birthday is on day " +
MyBirthdayDay.getDate() + ".");
}
Get Day of Week Method
The Get Day of Week method returns the day of the week of a date object as a number from 0 through 6. Sunday is 0 and Saturday is 6.
Format
dateVar.getDay()
To get the name of the corresponding weekday, you can create an array that contains the names of the days of the week, and then compare the return value to the array index. The following example gets the day of the week when New Year’s Day occurs:
function Button1_Click ()
{
var weekDay = new Array("Sunday", "Monday", "Tuesday",
"Wednesday", "Thursday", "Friday", "Saturday");
var NewYearsDay = new Date("2004", "1", "1");
var theYear = NewYearsDay.getFullYear()
var i = 0;
while (i < NewYearsDay.getDay())
{
i++;
var result = weekDay[i];
}
TheApplication().RaiseErrorText("New Year’s Day falls on " + result + " in " +
theYear + ".");
}
This example displays the following text:
New Year’s Day falls on Thursday in 2004.
Get Full Year Method
The Get Full Year method returns the year of a date object as a number with four digits.
Format
dateVar.getFullYear()
For examples, see the following topics:
Get Hours Method
The Get Hours method returns the hour of a date object. For more information, see Values for Dates and Times.
Format
dateVar.getHours()
The following example returns the number 12, which is the hours portion of the specified time:
var aDate = new Date("October 31, 1986 12:13:14");
TheApplication().RaiseErrorText(aDate.getHours());
Get Milliseconds Method
The Get Milliseconds method returns the milliseconds part of a date object as a number from 0 through 999. When given a date in milliseconds, it returns the last three digits of the millisecond date. If this value is negative, then it returns the result of the last three digits subtracted from 1000. For more information, see Values for Dates and Times.
Format
dateVar.getMilliseconds()
The following example gets the time from the system clock. The number of milliseconds past the beginning of the second occurs at the end of the message:
var aDate = new Date; TheApplication().RaiseErrorText( aDate.toString() + " " + aDate.getMilliseconds() );
Get Minutes Method
The Get Minutes method returns the minutes portion of a date object. For more information, see Values for Dates and Times.
Format
dateVar.getMinutes()
The following example returns the number 13, which is the minutes portion of the specified time:
var aDate = new Date("October 31, 1986 12:13:14");
TheApplication().RaiseErrorText(aDate.getMinutes());
Get Month Method
The Get Month method returns the month of a date object. For more information, see Values for Dates and Times.
Format
dateVar.getMonth()
The following example returns the number 10, with the result of adding 1 to the month portion of the specified date:
var aDate = new Date("October 31, 1986 12:13:14");
TheApplication().RaiseErrorText(aDate.getMonth() + 1);
Get Seconds Method
The Get Seconds method returns the seconds portion of a date object as a number from 0 through 59. For more information, see Values for Dates and Times.
Format
dateVar.getSeconds()
The following code returns the number 14, which is the seconds portion of the specified date:
var aDate = new Date("October 31, 1986 12:13:14");
TheApplication().RaiseErrorText(aDate.getSeconds());
Get Time Method
The Get Time method returns the number of milliseconds for a date object. It returns this value as an integer. This integer includes the number of seconds between midnight on January 1, 1970, GMT, and the date and time that the date object specifies.
Format
dateVar.getTime()
The following example returns a value of 245594000. To convert this value to a value that a person can interpret, you can use the Convert Date and Time to String method or the Convert Date to GMT String Method method:
var aDate = new Date("January 3, 1970 12:13:14");
TheApplication().RaiseErrorText(aDate.getTime());
For more information, see the following topics:
Get Time Zone Offset Method
The Get Time Zone Offset method returns the difference, in minutes, between UTC time and local time that it calculates as the UTC time minus the local time. For example, Central European Time (CET) is UTC plus 60. On a computer that is set to the CET time zone, the Get Time Zone Offset method returns a value of negative 60.
Format
dateVar.getTimezoneOffset()
The following example calculates the difference from UTC, in hours, of your location, according to the setting in the Windows Control Panel:
var aDate = new Date();
var hourDifference = Math.round(aDate.getTimezoneOffset() / 60);
TheApplication().RaiseErrorText("Your time zone is " +
hourDifference + " hours from GMT.");
Get Year Method
The Get Year method returns the year portion of a date object as the offset from a base year of 1900. The offset is positive for any year that occurs after 1900 and is negative for any year that occurs before 1900. For example, if the value of dateVar is a date in the year 2004, then dateVar.getYear equals 104.
Format
dateVar.getYear()
Set Date Method
The Set Date method sets the day of dateVar to the value you specify in the dayOfMonth argument.
Format
dateVar.setDate(dayOfMonth)
The following table describes the arguments for the Set Date method.
| Argument | Description |
|---|---|
dayOfMonth |
The day of the month to set in dateVar as an integer from 1 through 31. For more information, see Values for Dates and Times. |
Setting the Day to a Value That Exceeds 31
You can add any number of days to a date. Siebel eScript automatically converts the number of days to the correct month and year. For example, to add the number of days to a date, you can use the following script:
//script to add 7 days to a date var dtNextWeek = new Date(); dtNextWeek.setDate( dtNextWeek.getDate()+7 ); //script to add 76 days to a date var dtNextWeek = new Date(); dtNextWeek.setDate(dtNextWeek.getDate()+76);
Set Full Year Method
The Set Full Year method sets the year of a date object to a four digit year. Optionally, you can use Siebel eScript to set the month of the year argument to the month argument, and the date of the month argument to the date argument. You must express the year in four digits.
Format
dateVar.setFullYear(year[, month[, date]])
The following table describes the arguments for the Set Full Year method.
| Argument | Description |
|---|---|
year |
The year to set in dateVar as a four digit integer. |
month |
The month to set in dateVar as an integer from 0 through 11. For more information, see Values for Dates and Times. |
date |
The date to set in dateVar as an integer from 1 through 31. |
Set Hours Method
The Set Hours method sets the hour of a date object to an hour of a 24-hour clock. You can optionally set the UTC minute, second, and millisecond. For more information, see Values for Dates and Times.
Format
dateVar.setHours(hour[, minute[, second[, millisecond]]])
The following table describes the arguments for the Set Hours method.
| Argument | Description |
|---|---|
hour |
For more information, see Values for Dates and Times. |
minute |
|
second |
|
millisecond |
Set Milliseconds Method
The Set Milliseconds method sets the millisecond of a date object to a date expressed in milliseconds relative to the system time. The value of dateVar becomes equivalent to the number of milliseconds from the time on the system clock. You can use a positive number for a later time and a negative number for an earlier time.
Format
dateVar.setMilliseconds(millisecond)
The following table describes the arguments for the Set Milliseconds method.
| Argument | Description |
|---|---|
millisecond |
For more information, see Values for Dates and Times. |
Example
The following example accepts a number of milliseconds as input and converts it to the date relative to the date and time in the computer clock:
function test2_Click ()
{
var aDate = new Date;
var milli = 7200000;
aDate.setMilliseconds(milli);
var aYear = aDate.getFullYear();
var aMonth = aDate.getMonth() + 1;
var aDay = aDate.getDate();
var anHour = aDate.getHours();
switch(anHour)
{
case 0:
anHour = " 12 midnight.";
break;
case 12:
anHour = " 12 noon.";
break;
default:
if (anHour > 11 )
anHour = (anHour - 12 ) + " P.M.";
else
anHour = anHour + " A.M.";
}
TheApplication().RaiseErrorText("The specified date is " + aMonth + "/" + aDay +
"/" + aYear + " at " + anHour);
}
The number 7200000 milliseconds is two hours. If you run this code on November 22, 2005 between 3 P.M. and 4 P.M., then it provides the following result:
The specified date is 11/22/2005 at 5 P.M.
Set Minutes Method
The Set Minutes method sets the minute of dateVar to the value you specify in the minute argument. You can optionally set the minute argument to a specific second and millisecond. For more information, see Values for Dates and Times.
Format
dateVar.setMinutes(minute[, second[, millisecond]])
The following table describes the arguments for the Set Minutes method.
| Argument | Description |
|---|---|
minute |
For more information, see Values for Dates and Times. |
second |
|
millisecond |
Set Month Method
The Set Month method sets the month of dateVar to the value you specify in the month argument. You can optionally set the day of month to the date argument. For more information, see Values for Dates and Times.
Format
dateVar.setMonth(month[, date])
The following table describes the arguments for the Set Month method.
| Argument | Description |
|---|---|
month |
The month to set in dateVar as an integer from 0 through 11. |
date |
The date of the month argument to set in dateVar as an integer from 1 through 31. |
Set Seconds Method
The Set Seconds method sets the second of dateVar to the value you specify in the second argument. You can optionally use this method to set the second argument to the value that you specify in the millisecond argument.
Format
dateVar.setSeconds(second[, millisecond])
The following table describes the arguments for the Set Seconds method.
| Argument | Description |
|---|---|
second |
For more information, see Values for Dates and Times. |
millisecond |
Set Time Method
The Set Time method sets dateVar to a date that Siebel CRM determines from the value you specify in the milliseconds argument, calculated from January 1, 1970, GMT. To set a date earlier than this date, you can use a negative number.
Format
dateVar.setTime(milliseconds)
For more information about the milliseconds argument, see Values for Dates and Times.
Example
The following example uses a number of milliseconds as input and converts it to a date and hour:
function dateBtn_Click ()
{
var aDate = new Date;
var milli = -4000;
aDate.setTime(milli);
var aYear = aDate.getFullYear();
var aMonth = aDate.getMonth() + 1;
var aDay = aDate.getDate();
var anHour = aDate.getHours();
switch(anHour)
{
case 0:
anHour = " 12 midnight.";
break;
case 12:
anHour = " 12 noon.";
break;
default:
if ( anHour > 11 )
anHour = (anHour - 12) + " P.M.";
else
anHour = anHour + " A.M.";
}
TheApplication().RaiseErrorText("The specified date is " +
aMonth + "/" + aDay + "/" + aYear + " at " + anHour);
}
For example, if you enter a value of -345650, then this code provides the following result:
The specified date is 12/31/1969 at 3 P.M.
Set Year Method
The Set Year method sets the year of a date object as a two digit or four digit year that you specify.
Format
dateVar.setYear(year)
The following table describes the arguments for the Set Year method.
| Argument | Description |
|---|---|
year |
The year to set in dateVar. You can write code that uses one of the following values in the year argument:
|
UTC Methods
This topic describes UTC methods. It includes the following topics:
Convert UTC Date to Readable Date Method
The Convert UTC Date to Readable Date returns a string that includes the UTC date of dateVar in a format that a human can read. This string uses the following format:
Day Mon dd hh:mm:ss yyyy
Format
dateVar.toUTCString()
For an example, see Convert Date and Time to String Method.
Related Topics
For more information, see the following topics:
Get UTC Date Method
The Get UTC Date method returns an integer that includes the number of milliseconds before or after midnight January 1, 1970 of the date and time that you specify. To call this method, you use the date constructor rather than a variable. This method interprets the arguments as referring to GMT time. For more information, see Values for Dates and Times.
Format
Date.UTC(year, month, day, [, hours[, minutes[, seconds]]])
The following table describes the arguments for the Get UTC Date method.
| Argument | Description |
|---|---|
year |
An integer that contains the year. To represent a year that occurs in the twentieth century, you can use two digits. For more information, see Caution About Using Two Digit Dates. |
month |
For more information, see Values for Dates and Times. |
day |
|
hours |
|
minutes |
|
seconds |
Example
The following example uses the Get UTC Date method:
function clickme_Click ()
{
var aDate = new Date(Date.UTC(2005, 1, 22, 10, 11, 12));
TheApplication().RaiseErrorText("The specified date is " +
aDate.toUTCString());
}
This example provides the following result:
The specified date is Sat Jan 22 10:11:12 2005 GMT
For more information, see About the Date Constructor.
Get UTC Day of Month Method
The Get UTC Day of Month method returns the UTC day of the month of dateVar as a number from 1 to 31. For more information, see Values for Dates and Times.
Format
dateVar.getUTCDate()
The following example displays 1, the hour portion of the date, followed by the GMT equivalent, which can include the same value:
var aDate = new Date("May 1, 2005 13:24:35");
TheApplication().RaiseErrorText("Local day of the month is " +
aDate.getHours() +"\nGMT day of the month is " +
aDate.getUTCHours());
Get UTC Day of Week Method
The Get UTC Day of Week method returns the UTC day of the week of a date object as a number from 0 through 6. For more information, see Values for Dates and Times.
Format
dateVar.getUTCDay()
The following example displays the day of the week for May 1, 2005 in local time and in UTC time:
function Button2_Click ()
{
var localDay;
var UTCDay;
var MayDay = new Date("May 1, 2005 13:30:35");
var weekDay = new Array("Sunday", "Monday", "Tuesday",
"Wednesday", "Thursday", "Friday", "Saturday");
for (var i = 0; i <= MayDay.getDay();i++)
localDay = weekDay[i];
var msgtext = "May 1, 2005, 1:30 PM falls on " + localDay;
for (var j = 0; j <= MayDay.getUTCDay(); j++)
UTCDay = weekDay[j];
msgtext = msgtext + " locally, \nand on " + UTCDay + " GMT.";
TheApplication().RaiseErrorText(msgtext);
}
Get UTC Full Year Method
The Get UTC Full Year year method returns the UTC year of a date object as a four digit number.
Format
dateVar.getUTCFullYear()
The following example displays 2005, the year portion of the date, followed by the GMT equivalent, which can include the same value:
var aDate = new Date("January 1, 2005 13:24:35");
TheApplication().RaiseErrorText("Local year is " + aDate.getYear() +
"\nGMT year is " + aDate.getUTCFullYear());
Get UTC Hours Method
The Get UTC Hours Method returns the UTC hour of a date object as a number from 0 through 23. For more information, see Values for Dates and Times.
Format
dateVar.getUTCHours()
The following example displays a value of 13, which is the hour portion of the date, followed by the GMT equivalent:
var aDate = new Date("May 1, 2005 13:24:35");
TheApplication().RaiseErrorText("Local hour is “ + aDate.getHours() +
"\nGMT hour is " + aDate.getUTCHours());
Get UTC Milliseconds Method
The Get UTC Milliseconds method returns the UTC millisecond of a date object as a number from 0 through 999. For more information, see Values for Dates and Times.
Format
dateVar.getUTCMilliseconds()
Get UTC Minutes Method
The Get UTC Minutes method returns the UTC minute of a date object as a number from 0 through 59. For more information, see Values for Dates and Times.
Format
dateVar.getUTCMinutes()
The following example displays a value of 24, which is the minutes portion of the date, followed by the GMT equivalent:
var aDate = new Date("May 1, 2005 13:24:35");
TheApplication().RaiseErrorText("Local minutes: " + aDate.getMinutes() +
"\nGMT minutes: " + aDate.getUTCMinutes());
Get UTC Month Method
The Get UTC Month method returns the UTC month of a date object as a number from 0 through 11. For more information, see Values for Dates and Times.
Format
dateVar.getUTCMonth()
The following example displays a value of 5, which is the month portion of the date determined by adding 1 to the value that the Get UTC Month method returns. This value is followed by the GMT equivalent which is determined by adding 1 to the value that the Get UTC Month method returns:
var aDate = new Date("May 1, 2005 13:24:35");
var locMo = aDate.getMonth() + 1;
var GMTMo = aDate.getUTCMonth() + 1
TheApplication().RaiseErrorText("Local month: " + locMo +"\nGMT month: "
+ GMTMo);
Get UTC Seconds Method
The Get UTC Seconds method returns the UTC second of a date object as number from 0 through 59. For more information, see Values for Dates and Times.
Format
dateVar.getUTCSeconds()
Set UTC Date Method
The Set UTC Date method sets the UTC day of a date object to a number from 1 through 31 according to the value you set in the dayOfMonth argument.
Format
dateVar.setUTCDate(dayOfMonth)
The following table describes the arguments for the Set UTC Date method.
| Argument | Description |
|---|---|
dayOfMonth |
The day of the UTC month to set in dateVar as an integer from 1 through 31. For more information, see Values for Dates and Times. |
Set UTC Full Year Method
The Set UTC Full Year method sets the UTC year of a date object to a four digit year that you specify in the year argument.
Format
dateVar.setUTCFullYear(year[, month[, date]])
The following table describes the arguments for the Set UTC Full Year method.
| Argument | Description |
|---|---|
year |
The UTC year to set in dateVar as a four digit integer. You must express the year in four digits. |
month |
As an option, you can use the month argument and the date argument to set the month and date of the year. For more information, see Values for Dates and Times. |
date |
Example
The following example does the following work:
To assign the date of the 2000 summer solstice, it uses the Set UTC Full Year method
To assign time to a date object, it uses the Set UTC Hours method
Determines the local date and displays it
This example uses the following code:
function dateBtn_Click ()
{
var Mstring = " A.M., Standard Time.";
var solstice2K = new Date;
solstice2K.setUTCFullYear(2000, 5, 21);
solstice2K.setUTCHours(01, 48);
var localDate = solstice2K.toLocaleString();
var pos = localDate.indexOf("2000")
var localDay = localDate.substring(0, pos - 10);
var localHr = solstice2K.getHours();
if (localHr > 11 )
{
localHr = (localHr - 12 );
Mstring = " P.M., Standard Time.";
}
var localMin = solstice2K.getMinutes();
var msg = "In your location, the solstice is on " + localDay +
", at " + localHr + ":" + localMin + Mstring;
TheApplication().RaiseErrorText(msg);
}
This example produces the following result:
In your location, the solstice is on Tue Jun 20, at 6:48 P.M., Standard Time.
Set UTC Hours Method
The Set UTC Hours method sets the UTC hour of a date object to a specific hour of a 24-hour clock as a number from 0 through 23. As an option, you can also set the UTC minute, second, and millisecond.
Format
dateVar.setUTCHours(hour[, minute[, second[, millisecond]]])
The following table describes the arguments for the Set UTC Hours method.
| Argument | Description |
|---|---|
hour |
For more information, see Values for Dates and Times. |
minute |
|
second |
|
millisecond |
Example
For an example, see Set UTC Full Year Method.
Set UTC Milliseconds Method
The Set UTC Milliseconds method sets the UTC millisecond of a date object to a date expressed in milliseconds relative to the UTC equivalent of the system time. The value of dateVar becomes equivalent to the number of milliseconds from the UTC equivalent of the time on the system clock. You can use a positive number for later times or a negative number for earlier times.
Format
dateVar.setUTCMilliseconds(millisecond)
The following table describes the arguments for the Set UTC Milliseconds method.
| Argument | Description |
|---|---|
millisecond |
The UTC millisecond to set in dateVar as a positive or negative integer. For more information, see Values for Dates and Times. |
Example
The following example gets a number of milliseconds as input and converts it to a UTC date and time:
function dateBtn_Click ()
{
var aDate = new Date;
var milli = 20000;
aDate.setUTCMilliseconds(milli);
var aYear = aDate.getUTCFullYear();
var aMonth = aDate.getMonth() + 1;
var aDay = aDate.getUTCDate();
var anHour = aDate.getUTCHours();
var aMinute = aDate.getUTCMinutes();
TheApplication().RaiseErrorText("The specified date is " +
aMonth +
"/" + aDay + "/" + aYear + " at " + anHour + ":" +
aMinute + ", UTC time.");
}
If run at 5:36 P.M., PST (Pacific Standard Time), on August 22, 2005, then this example produced the following result:
The specified date is 8/23/2005 at 1:36 UTC time.
Set UTC Minutes Method
The Set UTC Minutes method sets the UTC minute of a date object to a minute that you specify in the minute argument.
Format
dateVar.setUTCMinutes(minute[, second[, millisecond]])
The following table describes the arguments for the Set UTC Minutes method.
| Argument | Description |
|---|---|
minute |
As an option, you can use the second argument to set the minute to a specific UTC second and the millisecond argument to set the minute to a UTC millisecond. For more information, see Values for Dates and Times. |
second |
|
millisecond |
Set UTC Month Method
The Set UTC Month method sets the UTC month of a date object to a specific month.
Format
dateVar.setUTCMonth(month[, date])
The following table describes the arguments for the Set UTC Month method.
| Argument | Description |
|---|---|
month |
The UTC month to set in dateVar as an integer from 0 through 11. As an option, you can set this argument to the value that the date argument contains. For more information, see Values for Dates and Times. |
date |
The UTC date of the month argument to set in dateVar as an integer from 1 through 31. |
Set UTC Seconds Method
The Set UTC Seconds method sets the UTC second of the minute of a date object to a second that you specify.
Format
dateVar.setUTCSeconds(second[, millisecond])
The following table describes the arguments for the Set UTC Seconds method.
| Argument | Description |
|---|---|
second |
As an option, you can set the second argument to a value that you specify in the millisecond argument. For more information, see Values for Dates and Times. |
millisecond |
Global Methods
This topic describes global methods. It includes the following topics:
Overview of Global Methods
A global method is a method of the global object.
A global variable is a member of a global object. To reference a global property, you do not need to use an object name. For example, to reference the Is NaN method that tests to determine if a value is equal to the special value NaN, you can use the format that this topic describes. For more information, see Is NaN Method.
The global methods that this book describes are unique to the Siebel eScript implementation of JavaScript. These methods are not part of the ECMAScript standard. Avoid using them in a script that you might use with a JavaScript interpreter that does not support them.
You can use format A or format B to call a global method.
Format A
globalMethod(value); Format A treats the globalMethod argument as a function. You cannot use format A in a function that includes a local variable that has the same name as a global variable. To reference the global variable in this situation, you must use the global keyword.
global.globalMethod(value);
Format B treats the globalMethod argument as a method of the global object.
Arguments
The following table describes the arguments of a global object.
| Argument | Description |
|---|---|
globalMethod |
The method that the global object applies. |
value |
The value that the global object applies to the method that you specify in the globalMethod argument. |
Related Topics
For more information, see the following topics:
Create COM Object Method
The Create COM Object method instantiates a COM object. It returns a successful COM object or an undefined object.
Format
COMCreateObject(objectName)
The following table describes the arguments for the Create COM Object method.
| Argument | Description |
|---|---|
objectName |
The name of the object that this method creates. |
Usage
You can configure Siebel CRM to pass any type of variable to the COM object that it calls. You must make sure the variable type is valid for the COM object. The following variable types are valid:
String
Number
Object pointer
Siebel CRM can run the Create COM Object method only in server script. It cannot run this method in browser script.
A DLL that the Create COM Object method instantiates must be thread-safe.
Using the Dispatch Identifier to Call a COM Method
Siebel CRM calls the method of a COM object in Siebel eScript in the same way that it calls this method in Siebel VB. In this context, a COM object is an object that the Create COM Object method instantiates.
To use the DISPID (Dispatch Identifier) of a COM method to call that COM method, you make an IDispatch::Invoke call in the COM technology. To identify methods, properties, and arguments, you use the Dispatch Identifier in the IDispatch::Invoke call.
You can write code that uses only the following arguments:
BSTR (basic string). An eScript string.
VARIANT. A universal data type.
SAFEARRAY. Similar to a typical C array, but also includes information about the number of elements in the array.
You cannot use Siebel eScript to call the method of a COM object that includes the LPCSTR argument for the string argument of that method. In this situation, you must use the BSTR argument.
Example
The following example instantiates Microsoft Excel as a COM object and makes it visible:
var ExcelApp = COMCreateObject("Excel.Application");
// Make Excel visible through the Application object.
ExcelApp.Visible = true;
ExcelApp.WorkBooks.Add();
// Place some text in the first cell of the sheet
ExcelApp.ActiveSheet.Cells(1,1).Value = "Column A, Row 1";
// Save the sheet
var fileName = "C:\\demo.xls";
ExcelApp.ActiveWorkbook.SaveAs (fileName);
// Close Excel with the Quit method on the Application object
ExcelApp.Application.Quit();
// Clear the object from memory
ExcelApp = null;
return (CancelOperation);
An application, such as Microsoft Excel, might change from version to version, so it might be necessary for you to modify your code to address these modifications. This example code was tested on Excel 2003.
Get Array Length Method
The Get Array Length method returns the length of a dynamically created array. This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
Note the following:
You can write code that uses the Get Array Length method only with a dynamically created array. You cannot use it with an array that is not created with the Array constructor and the new operator.
The length property is not available for a dynamically created array. A dynamically created array must use the Get Array Length method or the Set Array Length method when working with an array length.
If you work with an array that the array constructor and the new operator creates, then you must use the length property of the array.
For more information, see Set Array Length Method.
Format
getArrayLength(array[, minIndex])
The following table describes the arguments for the Get Array Length method.
| Argument | Description |
|---|---|
array |
The name of the array whose length this method must get. |
minIndex |
The index of the lowest element where this method starts counting. The first element of an array is typically at index 0. If you specify the minIndex argument, then Siebel CRM uses it to set to the minimum index, which is zero or less. |
Related Topics
For more information, see the following topics:
Set Array Length Method
The Set Array Length method sets the first index and length of an array. It sets the length of the array argument to a range that the minIndex argument and the length argument define.
If you specify all three arguments for this method, then the following occurs:
The minIndex argument is the minimum index of the resized array.
The length argument is the length of the resized array.
If an element resides outside the length of the resized array, then that element becomes undefined.
If you only specify two arguments, then this method uses the second argument as the length argument and sets the minimum index of the resized array to 0 by default.
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
Format
setArrayLength(array[, minIndex], length])
The following table describes the arguments for the Set Array Length method.
| Argument | Description |
|---|---|
array |
The name of the array whose length this method must set. |
minIndex |
The index of the lowest element where this method starts counting. This value must be 0 or less. If you use ST eScript code, then it is not appropriate to use the minIndex argument. If you use ST eScript code, then this code restricts the minimum index to zero only and assigns it by default. |
length |
The length of the array. |
Use Caution If You Define an Array That Includes a Negative Index
Use caution if you defined an array that includes a negative index.
Related Topics
For more information, see the following topics
Undefine Method
The Undefine method undefines a variable, object property, or value. Assume Siebel CRM defines a value, and then a defined method returns true for this value. If you use the Undefine method with this value, then the Is Defined method returns false. Undefining a value is not the same as setting a value to null.
The following example sets the n variable to 2, and then undefines the n variable:
var n = 2; undefine(n);
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
Format
undefine(value)
The following table describes the arguments for the Undefine method.
| Argument | Description |
|---|---|
value |
The variable or object property that this method must undefine. |
Example
The following example creates an object named o, and then defines an o.one property. It then undefines this property but the o object remains defined:
var o = new Object; o.one = 1; undefine(o.one);
Conversion Methods
This topic describes conversion methods. It includes the following topics:
Overview of Conversion Methods
You might encounter a situation where you must specify or control the types of variables or data. Some conversion methods include one argument that is a variable or data item that Siebel eScript converts to the data type that you specify in the name of the method. For example, the following code creates two variables:
var aString = ToString(123);
var aNumber = ToNumber("123");
In this example, Siebel eScript does the following work:
To create the aString variable, it converts the number 123 to a string.
To create the aNumber variable, it converts the string value "123" to a number.
It already created the aString variable with a value of "123", so the second code line can use the following format:
var aNumber = ToNumber(aString);
Convert String to Floating-Point Number Method
The Convert String to Floating-Point Number method converts an alphanumeric string to a floating-point decimal number. It returns a floating-point decimal number. If it cannot convert to a number the value that the string argument contains, then it returns the following value:
NaN
For more information, see NaN Numbers.
Format
parseFloat(string)
The following table describes the arguments for the Convert String to Floating-Point Number method.
| Argument | Description |
|---|---|
string |
The string that this method must convert. |
How the Convert String to Floating-Point Number Method Handles the String
The first character that is not a white space character must be a digit or a minus sign (-). For more information, see Use White Space to Improve Readability.
The Convert String to Floating-Point Number method does the following:
Ignores white space characters that occur at the beginning of the string
Treats the first period (.) in the string as a decimal point
Treats any digits that follow the first period as the fractional part of the number
Stops reading the string at the first nonnumeric character that occurs after the decimal point
Ignores the first nonnumeric character it encounters
Ignores all characters that occur after the first nonnumeric character
Converts the result into a number
Example
The following example returns a result of negative 234.37:
var num = parseFloat(" -234.37 profit");
Convert String to Integer Method
The Convert String to Integer method converts an alphanumeric string to an integer. It returns an integer. If it cannot convert the value that the string argument contains to a number, then it returns the following value:
NaN
For more information, see NaN Numbers.
Format
parseInt(string [,radix])
The following table describes the arguments for the Convert String to Integer method.
| Argument | Description |
|---|---|
string |
The string that this method converts. |
radix |
The base of the number system that this method uses in the return value. For example, if you set the radix argument to 8, then it returns the value as an octal number. |
Usage
If you do not specify the radix argument or if the value that the radix argument contains is zero, then the Convert String to Integer method uses a value of 10 for the radix unless the value that the string argument contains begins with one of the following values:
The character pairs 0x or 0X. It uses a value of 16 for the radix.
A zero and a valid octal digit. It uses a value of 8 for the radix. Any number zero through seven is a valid octal digit.
This method handles the string in the same way as the Convert String to Floating-Point Number method. For more information, see Convert String to Floating-Point Number Method.
Example
The following example returns a result of negative 234:
var num = parseInt(" -234.37 profit");
Convert Number to Exponential Notation Method
The Convert Number to Exponential Notation method converts a number to exponential notation. It returns the number that the numberVar variable contains, expressed in exponential notation to the number of decimal places that you specify in the len argument.
Format
numberVar.toExponential(len)
The following table describes the arguments for the Convert Number to Exponential Notation method.
| Argument | Description |
|---|---|
len |
The number of decimal places in the significant digits portion of the number. |
How the Convert Number to Exponential Notation Method Handles the Len Argument
The Convert Number to Exponential Notation method does one of the following depending on one of the following values that the len argument contains:
Less than the number of significant decimal places that the numberVar variable contains. It does one of the following:
If the number is five or greater, then it rounds the result up.
If the number is less than five, then it rounds the result down.
Greater than the number of significant decimal places that the numberVar variable contains. It pads the extra places with zeroes.
Negative. It creates an error.
Using a Multivalue List to Avoid Unexpected Rounding
If you must use a value that exceeds 253, then it is recommended that you use a calculated field that uses the sum of a multivalue list instead of using Siebel eScript. If Siebel CRM performs an operation that results in a value that exceeds 253, then it rounds this value to 253.
The largest number that the Siebel eScript engine can hold is 253. This number is equivalent to the following values:
9.00719925 x 1015, with rounding
9,007,199,254,740,992, without rounding
Example
The following example uses the Convert Number to Exponential Notation method:
var num = 1234.567 var num3 = num.toExponential(3) //returns 1.235e+3 var num2 = num.toExponential(0) //returns 1e+3 var num9 = num.toExponential(9) //returns 1.234567000e+3 var smallnum = 0.0001234 var smallnum2 = smallnum.toExponential(2) //returns 1.2e-4 var smallnumerr = smallnum.toExponential(-1) //throws error
Convert Number to Fixed Decimal Method
The Convert Number to Fixed Decimal method converts a number according to the decimal places that you specify. It returns the number that it converts. It allows you to express a number that includes a number of decimal places that you specify. For example, to express the results of a currency calculation that includes two decimal places.
This method does the same work as the Convert Number to Exponential Notation method. For more information, see Convert Number to Exponential Notation Method.
This method uses the same argument as the Convert Number to Exponential Notation method. For more information, see Convert Number to Exponential Notation Method.
Format
numberVar.toFixed(len)
The following example uses the Convert Number to Fixed Decimal method:
var profits=2487.8235 var profits3 = profits.toFixed(3) //returns 2487.824 var profits2 = profits.toFixed(2) //returns 2487.82 var profits7 = profits.toFixed(7) //returns 2487.8235000 var profits0 = profits.toFixed(0) //returns 2488 var profitserr = profits.toFixed(-1) //throws error
Convert Number to Precision Method
The Convert Number to Precision method converts a number to a number that includes a number of significant digits. It returns the converted number contained in the numberVar variable, expressed to the number of significant digits that you specify in the len argument.
This method allows you to express a number at a desired length. For example, the result of a scientific calculation might only require accuracy to a specific number of significant digits.
This method does one of the following depending on if the value that the len argument contains is:
Less than the number of significant decimal places that exist in the value that the numberVar variable contains. It does one of the following:
If the number is five or greater, then it rounds the result up.
If the number is less than five, then it rounds the result down.
Greater than the number of significant decimal places that exist in the value that the numberVar variable contains. It pads the extra digits with zeroes and adds a decimal point, if necessary.
This method uses the same argument as the Convert Number to Exponential Notation method. For more information, see Convert Number to Exponential Notation Method.
Format
numberVar.toPrecision(len)
The following example uses the Convert Number to Precision method:
var anumber = 123.45 var a6 = anumber.toPrecision(6) //returns 123.450 var a4 = anumber.toPrecision(4) //returns 123.5 var a2 = anumber.toPrecision(2) //returns 1.2e+2
Convert Special Characters to URL Method
The Convert Special Characters to URL method replaces special characters that a string contains with character combinations so that Siebel CRM can use the string with a URL. It returns a modified string.
Format
escape(string)
The following table describes the arguments for the Convert Special Characters to URL method.
| Argument | Description |
|---|---|
string |
A string that contains the characters that this method replaces. |
Usage
The character combinations include Unicode values. For a character in the standard ASCII set, this is the hexadecimal ASCII code of the character preceded by a percentage symbol (%). The standard ASCII set includes decimal values 0 through 127.
The following items remain in the string:
Uppercase letters
Lowercase letters
Numbers
Ampersand (@)
Asterisk (*)
Plus sign (+)
Underscore (_)
Period (.)
Forward slash (/)
This method replaces other characters with their respective Unicode sequence.
Example 1
The following example encodes a string. It does not replace the ampersand (@) or asterisk (*) characters:
var str = escape("@#$*96!");
This example provides the following result:
"@%23%24*96%21"
The following example encodes a string:
var encodeStr = escape("@#$*%!");
This example provides the following result:
"@%23%24*%25%21"
Convert Unicode to ASCII Method
The Convert Unicode to ASCII method converts Unicode character combinations that exist in a string to equivalent ASCII characters. It returns the revised string.
Format
unescape(string)
The following table describes the arguments for the Convert Unicode to ASCII method.
| Argument | Description |
|---|---|
string |
A string literal or string variable that contains the Unicode character combinations that this method converts. |
Example
The following example displays the string in the argument. The Convert Unicode to ASCII method converts the Unicode character combinations to printable characters. The %20 is the Unicode representation of the space character. The following example normally displays on a single line because a new line cannot break a string:
TheApplication().RaiseErrorText(unescape("http://obscushop.com/texis/
%20%20showcat.html?catid=%232029
rg=r133"));
This example produces the following result:
http://obscushop.com/texis/ showcat.html?catid=#2029 rg=r133
Convert Value to Boolean Method
The Convert Value to Boolean method converts a value to the Boolean data type. It returns a value that depends on the data type of the value that the value argument contains. This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
Format
ToBoolean(value)
The following table describes the arguments for the Convert Value to Boolean method.
| Argument | Description |
|---|---|
value |
The value that this method converts to a Boolean value. |
Values That the Convert Value to Boolean Method Returns
The following table describes the values that the Convert Value to Boolean method returns.
| Data Type | Return Value |
|---|---|
Boolean |
Value that the value argument contains. |
buffer |
This method returns one of the following values depending on if the buffer is empty:
|
null |
False |
number |
This method returns one of the following values:
For more information, see NaN Numbers. |
object |
True |
string |
This method returns one of the following values depending on if the string is empty:
|
undefined |
False |
Convert Value to Buffer Method
The Convert Value to Buffer method converts the value that the value argument contains to a sequence of ASCII bytes. It then places this value in a buffer. These bytes depend on the data type of the value that the value argument contains. This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
Format
ToBuffer(value)
The following table describes the arguments for the Convert Value to Buffer method.
| Argument | Description |
|---|---|
value |
The value that this method saves to a buffer. |
Values That the Convert Value to Buffer Method Returns
The following table describes the values that the Convert Value to Buffer method returns.
| Data Type | Return Value |
|---|---|
Boolean |
This method returns one of the following values:
false
true |
null |
This returns the following string: null |
number |
This method returns a value depending on which of the following values the value argument contains:
NaN
0
Infinity
For more information on the number object, see NaN Numbers. |
object |
This method returns the following string: [object Object] |
string |
This method returns the text of the string. |
undefined |
This method returns the following string: undefined |
Convert Value to Bytes Method
The Convert Value to Bytes method converts the value that the value argument contains to bytes, and then places this value in a buffer. This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
This method does not convert a Unicode value to a corresponding ASCII value. For example, it stores the Unicode string Hit as the following value:
\OH\Oi\Ot
This value is the following hexadecimal sequence:
00 48 00 69 00 74
Format
ToBytes(value)
The following table describes the arguments for the Convert Value to Bytes method.
| Argument | Description |
|---|---|
value |
The value that this method converts to bytes, and then places in a buffer. |
Convert Value to Integer Method
The Convert Value to Integer method converts the value that the value argument contains to an integer in the range of negative 2 15 through 2 15 minus 1. The equivalent nonexponential range is negative 32,768 through 32,767. It returns a value depending on which of the following values the value argument contains:
NaN. It returns the following value:
+0
+0. It returns the following value:
-0
POSITIVE_INFINITY or NEGATIVE_INFINITY. It returns the result.
A number. It rounds the integer part of this number toward zero, and then returns the integer.
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
This method uses the same arguments as the Convert Value to Integer 32 method. For more information, see Convert Value to Integer 32 Method.
Format
ToInteger(value)
To avoid an error, you must first pass the value that the value argument contains to the Is NaN method or to the Convert Value to Number method. To use the Convert Value to Number method, you can include a statement that uses the following format:
var x; x = toNumber(value); (if x == 'NaN'). . [error -handling statements]; . else ToInteger(value);
The Convert Value to Integer method truncates rather than rounds the value it receives. It rounds numbers toward 0. For example, it rounds negative 12.88 to negative 12. It rounds 12.88 to 12.
Related Topics
For more information, see the following topics:
Convert Value to Integer 32 Method
The Convert Value to Integer 32 method converts the value that the value argument contains to an integer in the range of negative 2 31 through 2 31 minus 1. The equivalent nonexponential range is negative 2,147,483,648 through 2,147,483,647. It returns a value depending on which of the following values the value argument contains:
NaN. It returns the following value:
NaN
+0 or -0. It returns the following value:
0
POSITIVE_INFINITY or NEGATIVE_INFINITY. It returns the following value:
Infinity
A number. It rounds the integer part of this number toward zero, and then returns the integer.
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function and NaN Numbers.
Format
ToInt32(value)
The following table describes the arguments for the Convert Value to Integer 32 method.
| Argument | Description |
|---|---|
value |
The value that this method converts. |
Usage
To avoid an error, you must first pass the value that the value argument contains to the Is NaN method or to the Convert Value to Number method. To use the Is NaN method, you include a statement that uses the following format:
if (isNaN(value)). . [error-handling statements]; . else ToInt32(value);
The Convert Value to Integer 32 method truncates rather than rounds the value it receives, so it rounds numbers toward 0. For example, it rounds negative 12.88 to negative 12. It rounds 12.88 to 12.
Convert Value to Unsigned Integer 16 Method
The Convert Value to Unsigned Integer 16 method converts the value that the value argument contains to an integer in the range of 0 through 2
16
minus 1. The nonexponential value is 0 through 65,535. It returns a value depending on which of the following values the value argument contains:
NaN. It returns the following value:
+0
+0. It returns the following value:
0
POSITIVE_INFINITY. It returns the following value:
Infinity
Any other value. It returns the absolute value of the integer part of the number, rounded toward 0. The absolute value does not include a positive sign or a negative sign.
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
This method uses the same argument as the Convert Value to Integer 32 method. For more information, see Convert Value to Integer 32 Method.
Format
ToUint16(value)
To avoid an error, you must first pass the value argument to the Is NaN method or to the Convert Value to Number method. To use the Convert Value to Number method, you can include a statement that uses the following format:
var x;i x = toNumber(value); (if x == 'NaN'). . [error -handling statements]; . else ToUint16(value);
The Convert Value to Unsigned Integer 16 method truncates rather than rounds the value it receives, so it rounds numbers toward 0. For example, it rounds 12.88 to 12.
Related Topics
For more information, see the following topics:
Convert Value to Unsigned Integer 32 Method
The Convert Value to Unsigned Integer 32 method converts the value that the value argument contains to an integer in the range of 0 through 2
32
minus 1. The nonexponential value is 0 through 4,294,967,296. It returns the same value as the Convert Value to Unsigned Integer 16 method. For more information, see Convert Value to Unsigned Integer 16 Method.
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
This method uses the same argument as the Convert Value to Integer 32 method. For more information, see Convert Value to Integer 32 Method.
Format
ToUint32(value)
To avoid an error, you must first pass the value argument to the Is NaN method or to the Convert Value to Number method. To use the Convert Value to Number method, you can include a statement that uses the following format:
if (isNaN(value)). . [error-handling statements]; . else ToUint32(value);
The Convert Value to Unsigned Integer 32 method truncates rather than rounds the value it receives, so it rounds numbers toward 0. For example, it rounds 12.88 to 12.
Related Topics
For more information, see the following topics:
Convert Value to Number Method
The Convert Value to Number method converts the value that the value argument contains to a number. It returns a value that depends on the original data type of the value that the value argument contains. Convert Value to Bytes Method describes these data types.
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
This method uses the same argument as the Convert Value to Integer 32 method. For more information, see Convert Value to Integer 32 Method.
Format
ToNumber(value)
The following table describes values that the Convert Value to Number method returns.
| Data Type | Return Value |
|---|---|
Boolean |
This method returns one of the following values, depending on if the value that the value argument contains is:
+0
1 |
buffer |
This method returns one of the following values, depending on if the conversion is:
NaN For more information on the number object, see NaN Numbers. |
string |
|
null |
0 |
number |
This method returns the value that the value argument contains. |
object |
NaN |
undefined |
Related Topics
For more information, see Round Number Method.
Convert Value to Object Method
The Convert Value to Object method converts the value that the value argument contains to an object. It returns a value that depends on the data type of the value that the value argument contains.
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
This method uses the same argument as the Convert Value to Integer 32 method. For more information, see Convert Value to Integer 32 Method.
Format
ToObject(value)
The following table describes data types of the value that the Convert Value to Object method returns.
| Data Type | Returns |
|---|---|
Boolean |
A new Boolean object that includes the value that the value argument contains. |
number |
A new number object that includes the value that the value argument contains. |
string |
A new string object that includes the value that the value argument contains. |
object |
The value that the value argument contains. |
null |
A run-time error. |
undefined |
Convert Value to String Method
The Convert Value to String method converts the value that the value argument contains to a string. It returns a value in the format of a Unicode string. The contents of this string depends on the data type of the value that the value argument contains.
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
This method uses the same argument as the Convert Value to Integer 32 method. For more information, see Convert Value to Integer 32 Method.
Format
ToString(value)
The following table describes values that the Convert Value to String method returns.
| Data Type | Return Values |
|---|---|
Boolean |
This method returns one of the following values, depending on if the value that the value argument contains is:
|
null |
This method returns the following string: null |
number |
This method returns a value depending on which of the following values the value argument contains:
A number. It returns a string that includes this number. For more information on the number object, see NaN Numbers. |
object |
This method returns the following string: [object Object] |
string |
This method returns the value that the value argument contains. |
undefined |
This method returns the following string: undefined |
Example
For an example, see Evaluate Expression Method.
Evaluate Expression Method
The Evaluate Expression method evaluates the value that the expression argument contains. It returns the value that it evaluates in the expression argument. If the expression argument is a string, then this method attempts to interpret the string as if it is JavaScript code. If this method:
Interprets the string. It returns the value in the expression argument.
Cannot interpret the string. It returns the following value:
undefined
If the expression is not a string, then this method returns the value that exists in the expression argument. For example, calling eval(5) returns the value 5.
Format
eval(expression)
The following table describes the arguments for the Evaluate Expression method.
| Argument | Description |
|---|---|
expression |
The expression that this method must evaluate. |
Example
The following example describes the result of using the Evaluate Expression method on different types of expressions. This method does the following work:
Interprets the string in the test[0] variable because it can interpret this string as a JavaScript statement.
Does not interpret the string in the test[1] variable or the test[3] variable because it cannot interpret either string as a JavaScript statement. It returns a value of undefined for each of these variables.
This example includes the following code:
function clickme_Click ()
{
var msgtext = "";
var a = 7;
var b = 9;
var test = new Array(4);
var test[0] = "a * b";
var test[1] = ToString(a * b);
var test[2] = a + b;
var test[3] = "Strings are undefined.";
var test[4] = test[1] + test[2];
for (var i = 0; i < 5; i++)
msgtext = msgtext + i + ": " + eval(test[i]) + "\n";
TheApplication().RaiseErrorText(msgtext);
Running this code produces the following result:
0: 63 1: undefined 2: 16 3: undefined 4: undefined
Data Querying Methods
This topic describes data querying methods and objects that contain information. It includes the following topics:
Is Defined Method
The Is Defined method tests if a variable or object property is defined. It returns one of the following values:
The item is defined. It returns the following value:
True
The item is not defined. It returns the following value:
False
This method is unique to Siebel eScript. For more information, see Make Sure the JavaScript Interpreter Can Run a Function.
Format
defined(var)
The following table describes the arguments for the Is Defined method.
| Argument | Description |
|---|---|
var |
The variable or object property you must query. |
Example
The following example includes two uses of the Is Defined method. The first use examines a variable named t. The second use examines an object named t.t:
var t = 1;
if (defined(t))
TheApplication().Trace("t is defined");
else
TheApplication().Trace("t is not defined");
if (!defined(t.t))
TheApplication().Trace("t.t is not defined"):
else
TheApplication().Trace("t.t is defined");
For more information, see Undefine Method.
Is Finite Method
The Is Finite method determines if the value that the value argument contains is a finite number. It returns one of the following values:
It can convert the value to a number. It returns the following value:
True
The value evaluates to any of the following items. It returns False:
NaN
POSITIVE_INFINITY
NEGATIVE_INFINITY
For more information, see NaN Numbers.
This method uses the same argument as the Is NaN method. For more information, see Is NaN Method.
Format
isFinite(value)
Is NaN Method
The Is NaN method determines if the value that the value argument contains is a number. It returns one of the following values:
The value is a number. It returns the following value:
True
The value is not a number. It returns the following value:
False
If the value argument references an object, then the Is NaN method always returns true because an object reference is not a number. For more information on the number object, see NaN Numbers.
Format
isNaN(value)
The following table describes the arguments for the Is NaN method.
| Argument | Description |
|---|---|
value |
The variable or expression that this method evaluates. |
Example
The following examples use the Is NaN method:
IsNaN("123abc") //returns true
IsNaN("123") //returns false
IsNaN("999888777123") //returns false
IsNaN("The answer is 42") //returns true
For more information, see Is Finite Method.
Exception Object
If an operation fails, then the Siebel eScript engine creates an exception in the exception object.
The following table describes the arguments for the exception object.
| Argument | Description |
|---|---|
| errCode |
Contains the error number. |
| errText |
Contains a textual description of the error. |
Example
The following example includes an exception object:
try } var oBO = TheApplication().GetService(“Incorrect name”); } catch (e) } var sText = e.errText; var nCode = e.errCode; }
Function Object
A Function object contains the definition of a function that you define in Siebel eScript. It returns the code that you configure this function to return. For more information, see Return Statement of a Function Object.
Format A
function funcName( [arg1 [, ..., argn]] )
{
body
}
In format A you declare a function, and then call it in your code. It is the standard way to define a function.
Format B
var funcName = new Function([arg1 [, ..., argn,]] body );
In format B you explicitly create a function. If you use format B to create a function object, then Siebel CRM evaluates it each time it uses this function. This configuration is not as efficient as format A because Siebel CRM compiles a declared function only one time instead of evaluating it every time it uses the function.
Arguments
The following table describes the arguments for a function object.
| Argument | Description |
|---|---|
funcName |
The name of the function. |
arg1 [, …, argn] |
An optional list of arguments that the function accepts. |
body |
The lines of code that the function runs. |
Example 1
The following example uses format A to declare a function named AddTwoNumbers. It uses AddTwoNumbers as the name of the function:
function AddTwoNumbers (a, b)
{
return (a + b);
}
The following example uses format B to create a function named AddTwoNumbers. It uses the Function constructor to create a variable named AddTwoNumbers. The value of this variable is a reference to the function that the Function constructor creates:
AddTwoNumbers = new Function ("a", "b", "return (a + b)");
Length Property of a Function Object
The length property returns the number of arguments that the function expects.
Format
funcName.length
The following table describes the arguments for the length property.
| Argument | Description |
|---|---|
funcName |
The name of the function that the length property uses to return the number of arguments. |
Return Statement of a Function Object
The Return statement passes a value back to the function that called it.
Format
return value
The following table describes the arguments for the Return statement.
| Argument | Description |
|---|---|
value |
Contains a value from the function that calls the Return statement. |
Usage
Siebel CRM does not run any code in a function that occurs after a Return statement.
If you define a return type for a custom function, then you must explicitly return a value of the same type that the function header specifies. All control paths must lead to a Return statement.
Example 1
The function in the following example returns a value that is equal to the number that Siebel CRM passes to it multiplied by 2, and then divided by 5:
function DoubleAndDivideBy5(a)
{
return (a*2)/5
}
The following example does the following work:
Uses the value from the function in Return Statement of a Function Object
Calculates the following expression:
n = (10 * 2) / 5 + (20 * 2) / 5
Displays the value for n, which is 12:
function myFunction()
{
var a = DoubleAndDivideBy5(10);
var b = DoubleAndDivideBy5(20);
TheApplication().RaiseErrorText(a + b);
}
Mathematical Methods
This topic describes mathematical methods. It includes the following topics:
For more information on the number object, see NaN Numbers.
Overview of Mathematical Methods
Some math methods return data in radians. To convert radians to degrees, you can use the following formula:
radians multiplied by (180/Math.PI).
Properties of the Math Object
This topic describes properties of the math object.
Base E Property
The Base E property stores the number value for e, which is the base for natural logarithms. The value of e internally is approximately 2.7182818284590452354.
Format
Math.E
Logarithm 2 E Property
The Logarithm 2 E property stores the number value for the base 2 logarithm of e, which is the base of the natural logarithms. The value of the base 2 logarithm of e internally is approximately 1.4426950408889634. The value of the Logarithm 2 E property is approximately the reciprocal of the value of Math Logarithm 2 property.
Format
Math.LOG2E
Logarithm 10 E Property
The Logarithm 10 E property is the number value for the base 10 logarithm of e, which is the base of the natural logarithms. The value of the base 10 logarithm of e internally is approximately 0.4342944819032518. The value of the Logarithm 10 E property is approximately the reciprocal of the value of the Natural Logarithm 10 property.
Format
Math.LOG10E
Natural Logarithm 2 Property
The Natural Logarithm 2 property stores the number value for the natural logarithm of 2. The value of the natural logarithm of 2 internally is approximately 0.6931471805599453.
Format
Math.LN2
Math Natural Logarithm 10 Property
The Natural Logarithm 10 property stores the number value for the natural logarithm of 10. The value of the natural logarithm of 10 internally is approximately 2.302585092994046.
Format
Math.LN10
PI Property
The Pi property holds the number value for pi, which is the ratio of the circumference of a circle to the diameter of the circle. This value internally is approximately 3.14159265358979323846.
Format
Math.PI
Square Root 1/2 Property
The Square Root 1/2 property stores the number value for the square root of ½. This value internally is approximately 0.7071067811865476. The value of the Square Root 1/2 property is approximately the reciprocal of the value of the Square Root 2 property.
Format
Math.SQRT1_2
Square Root 2 Property
The Square Root 2 property stores the number value for the square root of 2. This value internally is approximately 1.4142135623730951.
Format
Math.SQRT2
Get Absolute Value Method
The Get Absolute Value method returns the absolute value of the value that the number argument contains. If it cannot convert this value to a number, then it returns NaN.
Format
Math.abs(number)
The following table describes the arguments for the Get Absolute Value method.
| Argument | Description |
|---|---|
number |
A numeric literal or numeric variable. |
Get Arc Cosine Method
The Get Arc Cosine method returns the arc cosine of the value that the number argument contains, expressed in radians from 0 to pi. If any of the following situations are true, then it returns NaN:
The method cannot convert the value to a number.
The value is greater than 1 or less than negative 1.
This method uses the same argument as the Get Absolute Value method. For more information, see Get Absolute Value Method.
Format
Math.acos(number)
Get Arcsine Method
The Get Arcsine method returns an approximate arcsine of the value that the number argument contains expressed in radians in the range of negative pi/2 through pi/2. If any of the following situations are true, then this method returns NaN:
It cannot convert the value to a number.
The value is greater than 1 or less than negative 1.
This method uses the same argument as the Get Absolute Value method. For more information, see Get Absolute Value Method.
Format
Math.asin(number)
Get Arctangent Method
The Get Arctangent method returns an approximate arctangent of the value that the number argument contains, expressed in radians and ranging from negative pi/2 through pi/2.
This method assumes the value that the number argument contains is the ratio of the following sides of a right triangle:
The side that is opposite of the angle that this method must calculate
The side that is adjacent to the angle
It returns a value for this ratio.
This method uses the same argument as the Get Absolute Value method. For more information, see Get Absolute Value Method.
Format
Math.atan(number)
The following example calculates the roof angles that are necessary for a house that includes the following dimensions:
An attic ceiling height of 8 feet at the roof peak
A 16 foot span from the outside wall to the center of the house
The Get Arctangent method returns the angle in radians. To convert the value to degrees, it multiplies it by 180/PI. To examine how the Get Arctangent method is different from the Get Arctangent 2 method, you can compare it to the example in the Get Arctangent 2 Method topic. These examples return the same value:
function RoofBtn_Click ()
{
var height = 8;
var span = 16;
var angle = Math.atan(height/span)*(180/Math.PI);
TheApplication().RaiseErrorText("The angle is " +
Clib.rsprintf("%5.2f", angle) + " degrees.")
}
Get Arctangent 2 Method
The Get Arctangent 2 method returns an approximate arctangent of the value that the y argument contains divided by the value that the x argument contains, expressed in radians and ranging from negative pi through pi.
To determine the quadrant of the result, this method uses the signs of the arguments. It is intentional and traditional that the argument named y is the first argument and the argument named x is the second argument.
Format
Math.atan2(y, x)
The following table describes the arguments for the Get Arctangent 2 method.
| Argument | Description |
|---|---|
y |
The value on the y axis. |
x |
The value on the x axis. |
Example for the Get Arctangent 2 Method
The following example finds the roof angle necessary for a house. It is identical to the example for the Get Arctangent method except this example uses the Get Arctangent 2 method. For more information, see Get Arctangent Method:
function RoofBtn2_Click ()
{
var height = 8;
var span = 16;
var angle = Math.atan2(span, height)*(180/Math.PI);
TheApplication().RaiseErrorText("The angle is " +
Clib.rsprintf("%5.2f", angle) + " degrees.")
}
Get Ceiling Method
The Get Ceiling method returns the smallest integer that is not less than the value that the number argument contains. If this argument already contains an integer, then this method returns the value of this argument. If it cannot convert the value to a number, then it returns the following value:
NaN
This method uses the same argument as the Get Absolute Value method. For more information, see Get Absolute Value Method.
Format
Math.ceil(number)
The following example creates a random number between 0 and 100 and displays the integer range where the number falls. Each run of this code produces a different result:
var x = Math.random() * 100;
TheApplication().RaiseErrorText("The number is between " +
Math.floor(x) + " and " + Math.ceil(x) + ".");
Get Cosine Method
The Get Cosine method returns an approximate cosine of the value that the number argument contains, expressed in radians.The return value is between negative 1 and 1. The angle can be positive or negative. If this method cannot convert the value to a number, then it returns the following value:
NaN
This method uses the same argument as the Get Absolute Value method. The only difference is that the number argument for the Get Cosine method includes an angle in radians. For more information, see Get Absolute Value Method.
Format
Math.cos(number)
The following example finds the length of a roof, given the roof pitch and the distance of the house from the center of the house to the outside wall of the house:
function RoofBtn3_Click ()
{
var pitch;
var width;
var roof;
pitch = 35; pitch = Math.cos(pitch*(Math.PI/180)); width = 75; width = width / 2; roof = width/pitch;
TheApplication().RaiseErrorText("The length of the roof is " +
Clib.rsprintf("%5.2f", roof) + " feet.");
}
Get Exponential Method
The Get Exponential method returns e raised to the power of x where:
e is the base of the natural logarithms. The value of e internally is approximately 2.7182818284590452354.
x is the value that the number argument contains.
If this method cannot convert the value that the number argument contains to a number, then it returns the following value:
NaN
Format
Math.exp(number)
The following table describes the arguments for the Get Exponential method.
| Argument | Description |
|---|---|
number |
The exponent value of the base of e. |
Related Topics
For more information, see the following topics:
Get Floor Method
The Get Floor method returns the greatest integer that is not greater than the value that the number argument contains. If this value is already an integer, then it returns the value that the number argument contains. If this method cannot convert the value that the number argument contains to a number, then it returns the following value:
NaN
This method uses the same argument as the Get Absolute Value method. For more information, see Get Absolute Value Method.
Format
Math.floor(number)
For an example, see Get Ceiling Method.
Get Logarithm Method
The Get Logarithm method returns an approximate natural logarithm of the value that the number argument contains.
This method uses the same argument as the Get Absolute Value method. For more information, see Get Absolute Value Method.
Format
Math.log(number)
For a large number, you must use the Get Logarithm method. The number 999^1000 (999 to the 1000th power) is an example of a large number. If you use the Raise Power method instead of the Get Logarithm method with a large number, then the Raise Power method returns the following value:
Infinity
Example
This example uses the Get Logarithm method to determine which of the following numbers is larger:
999^1000 (999 to the 1000th power)
1000^999 (1000 to the 999th power):
function Test_Click ()
{
var x = 999;
var y = 1000;
var a = y*(Math.log(x));
var b = x*(Math.log(y))
if ( a > b )
TheApplication().
RaiseErrorText("999^1000 is greater than 1000^999.");
else
TheApplication().
RaiseErrorText("999^1000 is not greater than 1000^999.");
}
Get Maximum Method
The Get Maximum method returns the larger of the values in the x argument and the y argument. If it cannot convert the value that the number argument contains to a number, then it returns the following value:
NaN
Format
Math.max(x, y)
The following table describes the arguments for the Get Maximum method.
| Argument | Description |
|---|---|
x |
A numeric literal or numeric variable. |
y |
A numeric literal or numeric variable. |
Related Topics
For more information, see Get Minimum Method.
Get Minimum Method
The Get Minimum method returns the smaller of the values that the x argument and the y argument contain. If it cannot convert the value that the number argument contains to a number, then it returns the following value:
NaN
This method uses the same argument as the Math Maximum method. For more information, see Get Maximum Method.
Format
Math.min(x, y)
Get Quotient Method
The Get Quotient method returns the quotient after a division operation that the Clib Divide method performs. You use this method in conjunction with the Clib Divide method.
Format
intVar.quot
The following table describes the arguments for the Get Quotient method.
| Argument | Description |
|---|---|
intVar |
Any variable that contains an integer. |
Example
For an example, see Clib Divide Method.
Get Random Number Method
The Get Random Number method creates, and then returns a pseudo-random number between 0 and 1. It uses no arguments.
Where possible, you must use the Get Random Number method instead of the Clib Create Random Number method. You use the Clib Create Random Number method only if you must use the Clib Initialize Random Number Generator method to create an initial value for the random number generator. For more information, see the following topics:
Format
Math.random()
The following example creates a random string of characters in a range. The Get Random Number method sets the range between lowercase letter a through lowercase letter z:
function Test_Click ()
{
var str1 = "";
var letter;
var randomvalue;
var upper = "z";
var lower = "a";
upper = upper.charCodeAt(0);
lower = lower.charCodeAt(0);
for (var x = 1; x < 26; x++)
{
randomvalue = Math.round(((upper - (lower + 1)) *
Math.random()) + lower);
letter = String.fromCharCode(randomvalue);
str1 = str1 + letter;
}
TheApplication().RaiseErrorText(str1);
}
Get Remainder Method
The Get Remainder method returns the remainder after a division operation that the Clib Divide method performs. You use this method in conjunction with the Clib Divide method.
Format
intVar.rem
The following table describes the arguments for the Get Remainder method.
| Argument | Description |
|---|---|
intVar |
Any variable that contains an integer. |
Example
For an example, see Clib Divide Method.
Get Sine Method
The Get Sine method returns the sine of an angle, expressed in radians. It returns the sine of the value that the number argument contains. The return value is between negative 1 and 1. If this method cannot convert the value that the number argument contains, then it returns the following value:
NaN
Format
Math.sin(number)
The following table describes the arguments for the math sine method.
| Argument | Description |
|---|---|
number |
A numeric expression that contains a number that includes the size of an angle, expressed in radians. This number can be positive or negative. |
Get Square Root Method
The Get Square Root method returns the square root of the value that the number argument contains. If the value that the number argument contains is a negative number or if this method cannot convert this value to a number, then it returns the following value:
NaN
This method uses the same argument as the Get Absolute Value method. For more information, see Get Absolute Value Method.
Format
Math.sqrt()
Get Tangent Method
The Get Tangent method returns the tangent of the value that the number argument contains. If it cannot convert the value that the number argument contains, then it returns the following value:
NaN
Format
Math.tan(number)
The following table describes the arguments for the Get Tangent method.
| Argument | Description |
|---|---|
number |
A numeric expression that contains the number of radians in the angle whose tangent this method returns. |
Raise Power Method
The Raise Power method raises the value that the x argument contains to the power of the value that the y argument contains. It returns the result in the x argument. For more information, see Get Logarithm Method.
Format
Math.pow(x, y)
The following table describes the arguments for the Raise Power method.
| Argument | Description |
|---|---|
x |
The number that this method raises. |
y |
The power to which this method raises the value that the x argument contains. |
Example
This example uses the Raise Power method to determine which of the following numbers is larger:
99^100 (99 to the 100th power)
100^99 (100 to the 99th power):
function Test_Click ()
{
var a = Math.pow(99, 100);
var b = Math.pow(100, 99);
if ( a > b )
TheApplication().RaiseErrorText("99^100 is greater than 100^99.");
else
TheApplication().RaiseErrorText("99^100 is not greater than 100^99.");
}
Round Number Method
The Round Number method does the following:
If the fractional part is equal to or greater than 0.5, then it rounds the value in the number argument up.
If the fractional part is less than 0.5, then it rounds the value in the number argument down.
It rounds a positive number or a negative number to the nearest integer.
It returns the integer that is closest in value to the value that the number argument contains.
This method uses the same argument as the Get Absolute Value method. For more information, see Get Absolute Value Method.
Format
Math.round(number)
The following example uses the Round Number method:
var a = Math.round(123.6); var b = Math.round(-123.6) TheApplication().RaiseErrorText(a + "\n" + b)
This example provides the following results:
124 negative 124
The following example illustrates precision loss due to rounding:
var n = 34.855; n = n* 100; var r = Math.round(n)
The value of the n variable is 3485.499999999999995 instead of 3485.5. Rounding this value results in a value of 3485 instead of 3486.
The following example avoids loss of precision due to rounding:
var n = parseFloat(34.855); n = parseFloat(n1b*100.0); var r = Math.round(n);
If you multiply or divide a value, and then round that value, then rounding might not be precise. Multiplication and division can cause precision loss.
Regular Expression Methods
This topic describes regular expression methods. It includes the following topics:
Overview of Regular Expression Methods
A regular expression is an object instance of a character pattern that is associated with attributes that ECMAScript uses to perform a character pattern search of a string. A regular expression uses the following short format:
RegExp
For more information, see ECMAScript specifications.
The Siebel T eScript engine supports the following methods of the regular expression object. The Siebel ST eScript engine does not support these methods:
RegExp.$n, including '$_' and '$&'
RegExp.input
RegExp.lastMatch
RegExp.lastParen
RegExp.leftContext
RegExp.rightContext
If you must use ST eScript code, then instead of using one of these methods you must modify your script to use an equivalent function on the target object.
Properties of Regular Expressions
This topic describes properties of regular expressions. The Siebel ST eScript engine and the Siebel T eScript engine supports these properties. Throughout this topic, the term regexp represents an object instance of a regular expression.
You can write code that uses the Compile Regular Expressions method to modify the attribute of a regular expression instance for one of these properties. For example, if you must write code that modifies the global attribute of a regular expression instance. For more information, see Compile Regular Expressions Method.
Regular Expression Global Property
The Regular Expression Global property is a read-only property that indicates the value of the global attribute of an instance of the regular expression object. The value it returns depends on the attribute:
The value g is an attribute of the regular expression. It returns the following value:
True
The value g is not an attribute of the regular expression. It returns the following value:
False
Format
regexp.global
The following example uses the regular expression global property:
// Create RegExp instance with global attribute.
var pat = /^Begin/g;
//or
var pat = new RegExp("^Begin", "g");
//Then pat.global == true.
Regular Expression Ignore Case Property
The Regular Expression Ignore Case property is a read-only property that indicates the value of the ignoreCase attribute of an instance of the regular expression object. The value it returns depends on the attribute:
The value i is an attribute of the regular expression. It returns the following value:
True
The value i is not an attribute of the regular expression. It returns the following value:
False
Format
regexp.ignoreCase
The following example uses the Regular Expression Ignore Case property:
// Create RegExp instance with ignoreCase attribute.
var pat = /^Begin/i;
//or
var pat = new RegExp("^Begin", "i");
//Then pat.ignoreCase == true.
Regular Expression Multiline Property
The Regular Expression Multiline property is a read-only property that indicates the value of the multiline attribute of an instance of the regular expression object. It determines if Siebel CRM performs a pattern search in multiline mode. The value it returns depends on the attribute:
The value m is an attribute of the regular expression. It returns the following value:
True
The value m is not an attribute of the regular expression. It returns the following value:
False
Format
regexp.multiline
The following example uses the Regular Expression Multiline property:
// Create RegExp instance with multiline attribute.
var pat = /^Begin/m;
//or
var pat = new RegExp("^Begin", "m");
//Then pat.multiline == true.
Regular Expression Source Property
The Regular Expression Source property is a read-only property that stores the regular expression that Siebel CRM uses to find matches in a string, not including the attributes.
Format
regexp.source
The following example uses the Regular Expression Source property:
var pat = /t.o/g; // Then pat.source == "t.o"
Compile Regular Expressions Method
The Compile Regular Expressions method modifies the pattern and attributes for the current instance of a regular expression object. It allows you to use a regular expression instance multiple times with modifications to the characteristics of this instance. You use it with a regular expression that the constructor function creates. You do not use this method with the literal notation.
Format
regexp.compile(pattern[, attributes])
The following table describes the arguments for the Compile Regular Expressions method.
| Argument | Description |
|---|---|
pattern |
A string that contains a new regular expression. |
attributes |
A string that contains new attributes. If you include the attributes argument, then this string must be empty, or it must contain one or more of the following characters:
|
Example
The following example uses the Compile Regular Expressions method:
var regobj = new RegExp("now");
// use this RegExp object
regobj.compile("r*t");
// use it some more
regobj.compile("t.+o", "ig");
// use it some more
For more information, see the following topics:
Get Regular Expression from String Method
The Get Regular Expression from String method searches the string that you specify in the str argument for a regular expression. It returns one of the following depending on if it finds this regular expression:
It finds the regular expression. It returns an array of strings that includes information about each match it finds and the property sets for these matches.
It does not find the regular expression. It returns the following value:
Null
Format
regexp.exec(str)
The following table describes the arguments for the Get Regular Expression from String method.
| Argument | Description |
|---|---|
str |
A string that this method searches for a regular expression. |
Usage Without Setting the Global Attribute
Assume you configure Siebel CRM to run the Get Regular Expression from String method, you do not set the g global attribute on the regular expression instance, and the method finds a match. In this situation, the array elements that it returns include the following information:
Element 0. The first text in the string that matches the primary regular expression.
Element 1. The text that the first subpattern of the regular expression instance matches. It encloses this subpattern in parentheses.
Element 2 through element n. Each subsequent element uses the same format as element 1.
The returned array includes the following properties:
Length property. The number of text matches that exist in the returned array.
Index property. The start position of the first text that matches the primary regular expression.
Input property. The target string that the method searched.
Usage With Setting the Global Attribute
Assume you configure Siebel CRM to run the Get Regular Expression from String method but you do set the g global attribute on the regular expression instance. In this situation, this method returns the same result as if the global attribute is not set but the behavior is more complex, which allows more operations. It does the following work:
Begins searching at the position in the target string that the this.lastIndex property specifies.
After it finds a match, it sets the this.lastIndex property to the position after the last character in the matched text.
The this.lastIndex property possesses read and write capabilities. To find all matches of a pattern, you can configure this method to set the this.lastIndex property to the start position of the previous match that it found plus 1. This configuration causes this method to loop through a string. When it does not find a match, it resets the this.lastIndex property to 0.
Using the Get Regular Expression from String Method with the T eScript Engine
If you use code that you create with the T eScript engine, and if the Get Regular Expression from String method finds a match, then it sets the appropriate static properties of the regular expression object. For example, it sets the following properties:
RegExp.leftContext
RegExp.rightContext
RegExp.$n
And so on
This configuration provides more information about the matches.
Using the Get Regular Expression from String Method and the Get Regular Expression from String Var Method
The behavior of the Get Regular Expression from String method and the Get Regular Expression from StringVar method varies depending on if you set the global attribute on the regular expression:
You do not set the global attribute. The methods return the same array. The return values and the index and input properties are the same.
You do set the global attribute. The methods return different arrays.
For more information, see Get Character From String Method.
Example 1
The following example calls the Get Regular Expression from String method from a regular expression whose global attribute is not set:
function fn ()
{
var myString = new String("Better internet");
var myRE = new RegExp(/(.).(.er)/i);
var results = myRE.exec(myString);
var resultmsg = "";
for(var i =0; i < results.length; i++)
{
resultmsg = resultmsg + "return[" + i + "] = " + results[i] + "\n";
}
TheApplication().RaiseErrorText(resultmsg);
}
fn ();
This example provides the following output:
return[0] = etter \\First text that contains primary pattern ...er (any three
\\characters followed by "er")
return[1] = e \\First text matching the first subpattern (.) (any single
\\character) in the first text matching the primary pattern
return[2] = ter \\First text matching the second subpattern (.er) (any single
\\character followed by "er") in the first text matching
\\the primary pattern
The following example calls the Get Regular Expression from String method from a regular expression whose global attribute is set. This method returns all matches that exist of the primary pattern in a string of the regular expression, including matches that overlap:
function fn ()
{
var str = "ttttot tto";
var pat = new RegExp("t.t", "g");
var resultmsg = "";
while ((rtn = pat.exec(str)) != null)
{
resultmsg = resultmsg + "Text = " + rtn[0] + " Pos = " + rtn.index
+ " End = " + (pat.lastIndex - 1) + "\n";
pat.lastIndex = rtn.index + 1;
}
TheApplication().RaiseErrorText(resultmsg)
}
fn ();
This example provides the following output:
Text = ttt Pos = 0 End = 2 Text = ttt Pos = 1 End = 3 Text = tot Pos = 3 End = 5 Text = t t Pos = 5 End = 7
For more information, see the following topics:
Is Regular Expression in String Method
The Is Regular Expression in String method determines if a string includes a regular expression. It returns one of the following values:
If the string includes a regular expression, then it returns the following value:
True
If the string does not include a regular expression, then it returns the following value:
False
This method uses the same arguments as the Get Regular Expression from String method. For more information, see Get Regular Expression from String Method.
Format
regexp.test(str)
The Is Regular Expression in String method is equivalent to regexp.exec(str)!=null.
Usage for this method with T eScript code is the same as usage for the Get Regular Expression from String method. For more information, see Get Regular Expression from String Method.
You can write code that uses the Is Regular Expression in String method with the g global attribute set on the regular expression instance. This functionality uses the lastIndex property in the same way as the Get Regular Expression from String method. For more information, see Get Regular Expression from String Method.
Example
The following example includes the Is Regular Expression in String method:
var str = "one two three tio one"; var pat = /t.o/; rtn = pat.test(str); // Then rtn == true.
Siebel Library Methods
This topic describes the Siebel library methods that Siebel eScript uses to call external libraries and applications. It includes the following topics:
Siebel Library Call DLL Method
The Siebel Library Call DLL method calls a procedure from a dynamic link library in Microsoft Windows or a shared object in UNIX. It returns an integer.
Windows Format
SElib.dynamicLink(Library, Procedure, Convention[, [desc,] arg1, arg2, arg3, ..., argn])
SElib.dynamicLink(Library, Procedure[, arg1, arg2, arg3, ...argn])
In UNIX, Siebel CRM cannot use the Siebel Library Call DLL method to pass more than 22 arguments. These 22 arguments include the shared library name and the procedure name. You can configure Siebel CRM to pass up to 20 more arguments.
The following table describes the arguments for the Siebel Library Call DLL method.
| Argument | Description |
|---|---|
Library |
The library argument can include the following:
|
Procedure |
The name or ordinal number of the procedure in the library dynamic link method. |
Convention |
The calling convention. |
desc |
Passes a Unicode string. For example, WCHAR. |
arg1, arg2, arg3, ..., argn |
Arguments for the Siebel Library Call DLL method. |
Usage for the Convention Argument
The following table describes the calling conventions you must use with the Siebel Library Call DLL method.
| Value | Description |
|---|---|
CDECL |
Send the argument that appears last in the list first. For example, consider the following format: SElib.dynamicLink(Library, Procedure, Convention[, [desc,] arg1, arg2, arg3]) If arg1, arg2, and arg3 are defined, then this method sends the arguments in the following order:
The caller reads the arguments. The STDCALL value is almost always used in Win32. |
STDCALL |
|
PASCAL |
Send the argument that appears first in the list first. For example, consider the following format: SElib.dynamicLink(Library, Procedure, Convention[, [desc,] arg1, arg2, arg3]) If arg1, arg2, and arg3 are defined, then this method sends the arguments in the following order:
The callee reads the arguments. |
Usage if An Argument Is Not Defined
Siebel CRM passes values as 32-bit values. If an argument is not defined when Siebel CRM calls the Siebel Library Call DLL method, then it assumes that the argument is a 32-bit value. It passes the address of a 32-bit data element to the Siebel Library Call DLL method. This method then sets the value.
Usage If an Argument Is a Structure
SELib is a feature that Siebel eScript uses to call functions in the native DLLs. These DLLs can contain functions implemented in a third party language, such as C or C++. In this situation, an argument can include a structure.
If an argument is a structure, then it must include a structure that defines the binary data types in memory. Siebel CRM does the following:
Copies the structure to a binary buffer.
Calls the method.
Converts the binary data back into the data structure according to the rules defined in the Write BLOB Data method and the Clib Read From File method. It performs data conversion according to the current BigEndianMode setting.
For more information, see Write BLOB Data Method and Clib Read From File Method.
Example 1
The following example describes a proxy DLL that uses denormalized input values, creates the structure, and calls a method in the destination DLL:
#include <windows.h>
_declspec(dllexport) int __cdecl
score (
double AGE,
double AVGCHECKBALANCE,
double AVGSAVINGSBALANCE,
double CHURN_SCORE,
double CONTACT_LENGTH,
double HOMEOWNER,
double *P_CHURN_SCORE,
double *R_CHURN_SCORE,
char _WARN_[5] )
{
*P_CHURN_SCORE = AGE + AVGCHECKBALANCE + AVGSAVINGSBALANCE;
*R_CHURN_SCORE = CHURN_SCORE + CONTACT_LENGTH + HOMEOWNER;
strcpy(_WARN_, "SFD");
return(1);
}
The following example calls a DLL. This code uses the buffer for pointers and characters:
function TestDLLCall3()
{
var AGE = 10;
var AVGCHECKBALANCE = 20;
var AVGSAVINGSBALANCE = 30;
var CHURN_SCORE = 40;
var CONTACT_LENGTH = 50;
var HOMEOWNER = 60;
var P_CHURN_SCORE = Buffer(8);
var R_CHURN_SCORE = Buffer(8);
var _WARN_ = Buffer(5);
SElib.dynamicLink("jddll.dll", "score", CDECL,
FLOAT64, AGE,
FLOAT64, AVGCHECKBALANCE,
FLOAT64, AVGSAVINGSBALANCE,
FLOAT64, CHURN_SCORE,
FLOAT64, CONTACT_LENGTH,
FLOAT64, HOMEOWNER,
P_CHURN_SCORE,
R_CHURN_SCORE,
_WARN_);
var r_churn_score = R_CHURN_SCORE.getValue(8, "float");
var p_churn_score = P_CHURN_SCORE.getValue(8, "float");
var nReturns = r_churn_score + p_churn_score;
return(nReturns);
}
The following example calls a DLL function in the default codepage:
var sHello = "Hello";
Selib.dynamicLink("MyLib.dll", "MyFunc", CDECL, sHello);
The following example calls a DLL function that passes Unicode strings:
var sHello = "Hello";
Selib.dynamicLink("MyLib.dll", "MyFunc", CDECL, WCHAR, sHello);
The following example calls a DLL function that passes Unicode and nonUnicode strings:
var sHello = "Hello";
var sWorld = "world";
Selib.dynamicLink("MyLib.dll", "MyFunc", CDECL, WCHAR, sHello, sWorld);
The following example calls an external application and passes arguments 0, 0, and 5 to it:
SElib.dynamicLink("shell32", "ShellExecuteA", STDCALL, 0, "open",
"c:\\Grabdata.exe", 0, 0, 5).
For more information, see Clib Send Command Method.
Siebel Library Get Pointer Address Method
The Siebel Library Get Pointer Address method gets the address in memory of the first byte of data in a buffer variable. It returns the address of the pointer to the buffer variable. For more information, see Buffer Methods.
Format
SElib.pointer(bufferVar])
The following table describes the arguments for the Siebel Library Get Pointer Address method.
| Argument | Description |
|---|---|
bufferVar |
The name of a buffer variable. |
Example
The following example includes the Siebel Library Get Pointer Address method:
TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");
var v = new Buffer("Now");
// Collect "Now", the original value, for display.
TheApplication().Trace(v);
// Get the address of the first byte of v, "N"
var vPtr = SElib.pointer(v);
// Get the "N"
var p = SElib.peek(vPtr);
// Convert "N" to "P"
SElib.poke(vPtr,p+2);
// Display "Pow"
TheApplication().Trace(v);
TheApplication().TraceOff();
This example produces the following output:
COMMENT,Now COMMENT,Pow
For more information, see the following topics:
Siebel Library Peek Method
The Siebel Library Peek method reads, and then returns data from a position in memory.
Format
SElib.peek(address[, dataType])
The following table describes the arguments for the Siebel Library Peek method.
| Argument | Description |
|---|---|
address |
Identifies the address in memory that this method uses to read data. |
dataType |
The type of data that this method returns. You can specify one of the following types:
The default value is UWORD8. You can add the following prefix on some types:
The numeric suffix specifies the number of bytes to get. An example of a numeric suffix is 8 or 16. FLOAT80 is not available in Win32. |
Example
The following example uses the Siebel Library Peek method:
TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");
var v = new Buffer("Now");
// Collect "Now", the original value, for display.
TheApplication().Trace(v);
// Get the address of the first byte of v, "N"
var vPtr = SElib.pointer(v);
// Get the "N"
var p = SElib.peek(vPtr);
// Convert "N" to "P"
SElib.poke(vPtr,p+2);
// Display "Pow"
TheApplication().Trace(v);
TheApplication().TraceOff();
This example produces the following output:
COMMENT,Now COMMENT,Pow
For more information, see the following topics:
Siebel Library Write Data Method
The Siebel Library Write Data method writes data to a specific position in memory. It returns the address of the byte that immediately follows the data that it writes.
Format
SElib.poke(address, data[, dataType])
The following table describes the arguments for the Siebel Library Write Data method.
| Argument | Description |
|---|---|
address |
The starting address in memory where this method writes data. |
data |
The data that this method writes in memory. The data type of this data must match the type that you specify in the dataType argument. |
dataType |
For more information, see Siebel Library Peek Method. |
Example
The following example includes the Siebel Library Write Data method:
TheApplication().TraceOn("c:\\eScript_trace.txt","allocation","all");
var v = new Buffer("Now");
// Collect "Now", the original value, for display.
TheApplication().Trace(v);
// Get the address of the first byte of v, "N"
var vPtr = SElib.pointer(v);
// Get the "N"
var p = SElib.peek(vPtr);
// Convert "N" to "P"
SElib.poke(vPtr,p+2);
// Display "Pow"
TheApplication().Trace(v);
TheApplication().TraceOff();
This example produces the following output:
COMMENT,Now COMMENT,Pow
For more information, see the following topics:
Custom Methods
This topic describes custom methods. It includes the following topics:
Overview of Custom Methods
You can group variables and functions together in one variable, and then reference them as a group. A compound variable of this sort is an object where each individual item of the object is a property.
An object property is similar to a variable or a constant. An object method is similar to a function. To reference an object property, you use the name of the object and the name of the property, separated by a period:
object name.property
You can write code that uses any valid variable name as a property name. The following example assigns values to the width and height properties of a rectangle object, calculates the area of a rectangle, and then displays the result:
var Rectangle; Rectangle.height = 4; Rectangle.width = 6; TheApplication().RaiseErrorText(Rectangle.height * Rectangle.width);
An object allows you to work with groups of data in a consistent way. For example, instead of using a single object named Rectangle, you can use multiple Rectangle objects, where each of these objects includes a separate value for width and a separate value for height.
How the Constructor Function Creates an Object
A constructor function creates an object template. To create a rectangle object, the following example uses a constructor function:
function Rectangle(width, height)
{
this.width = width;
this.height = height;
}
The following keyword references the arguments that the constructor function receives:
this
You can think of the this keyword as meaning this object.
Example of Using a Constructor Function
To create a rectangle object, the following example uses the new operator to call the constructor function:
var joe = new Rectangle(3,4) var sally = new Rectangle(5,3);
This code creates the following rectangle objects:
Joe, with a width of 3 and a height of 4
Sally, with a width of 5 and a height of 3
This example creates a Rectangle class and two instances of this class. A constructor function creates objects that belong to the same class. Every object that a constructor function creates is an instance of that class.
Class instances share the same properties, although a single class instance can possess more unique properties. For example, adding the following code to the example adds a motto property to the joe rectangle. The sally rectangle does not include a motto property:
joe.motto = "Be prepared!";
How a Function Is Assigned to an Object
An object can contain a function and variables. A function assigned to an object is a method of that object.
A method uses the this operator to reference a method variable. The following example is a method that computes the area of a rectangle:
function rectangle_area()
{
return this.width * this.height;
}
Siebel CRM passes no arguments to this function, so it is meaningless unless an object calls it. This object provides values for this.width and this.height.
The following code assigns a method to an object:
joe.area = rectangle_area;
The function now uses the values for height and width that were defined when you created the joe rectangle object.
To assign a method in a constructor function, you can use the this keyword. The following example creates an object class named Rectangle that includes the rectangle_area method as a property:
function rectangle_area()
{
return this.width * this.height;
}
function Rectangle(width, height)
{
this.width = width;
this.height = height;
this.area = rectangle_area;
}
The method is available to any instance of the class. The following example sets the value of area1 to 12 and the value of area2 to 15:
var joe = Rectangle(3,4); var sally = Rectangle(5,3); var area1 = joe.area(); var area2 = sally.area();
About Object Prototypes
An object prototype lets you specify a set of default values for an object. If Siebel eScript accesses an object property that is not assigned a value, then it consults the prototype. If this property exists in the prototype, and if this property contains a value, then Siebel eScript uses that value for the object property.
How an Object Prototype Conserves Memory
An object prototype helps you to make sure that every instance of an object uses the same default values and that these instances conserve the amount of memory that Siebel CRM requires to run a script. The joe and sally rectangles are each assigned an area method when they are created in How a Function Is Assigned to an Object. Siebel CRM allocates memory for this function twice, even though the method is exactly the same in each instance. To avoid this redundant memory, you can place the shared function or property in an object prototype. In this situation, every instance of the object uses the same function instead of each instance using a copy of the function.
Example of Using an Object Prototype
The following example creates a rectangle object with an area method in a prototype:
function rectangle_area()
{
return this.width * this.height;
}
function Rectangle(width, height)
{
this.width = width;
this.height = height;
}
Rectangle.prototype.area = rectangle_area;
The following code can now reference the rectangle_area method as a method of any Rectangle object:
var area1 = joe.area(); var area2 = sally.area();
Adding Methods and Data to an Object Prototype
You can write code that adds methods and data to an object prototype at any time. You must define the object class but you do not have to create an instance of the object before you assign prototype values to it. If you assign a method or data to an object prototype, then Siebel CRM updates every instance of that object to include the prototype.
If you attempt to write to a property that Siebel CRM assigns through a prototype, then it creates a new variable for the newly assigned value. It uses this value for the value of this instance of the object property. Other instances of the object still refer to the prototype for their values. The following example specifies joe as a special rectangle whose area is equal to three times the width plus half the height:
function joe_area()
{
return (this.width * 3) + (this.height/2);
}
joe.area = joe_area;
This code creates a value for joe.area that supersedes the prototype value. In this example, this value is a function. The sally.area property is still the default value that this prototype defines. The joe instance uses the new definition for the area method.
You cannot write code that declares a prototype in a function scope.