4Statements Reference
Statements Reference
This chapter describes reference information for statements you can use in Siebel eScript. It includes the following topics:
Break Statement
The Break statement does the following:
Stops the innermost loop of the following statements:
For
While
Do
Controls the flow in a Switch statement.
Format A
break;
break label;
The following table describes the arguments you can use with the Break statement.
| Argument | Description |
|---|---|
label |
The name of the label that indicates where this statement must resume running the script. This label includes the name of a method or a function followed by a colon. |
Usage
You can write code that uses the Break statement only in the following situations:
In a loop. Stops the loop if the code no longer requires the loop.
In a Switch statement. Stops Siebel eScript from running any code that occurs after the Label statement. Causes Siebel eScript to exit the Switch statement.
If you use the Break statement in a nested loop, then it causes Siebel eScript to stop running the script only in this nested loop. If the Break statement occurs in a nested loop, then you can use the label argument to indicate the beginning of the loop that Siebel eScript must stop.
Example
For an example, see Switch Statement.
Continue Statement
The Continue statement starts a new iteration of a loop. It ends the current iteration of a loop, and then begins the next loop. Siebel eScript evaluates any conditional expressions before the loop reiterates.
Format A
continue;
continue label;
The following table describes the argument.
| Argument | Description |
|---|---|
label |
The name of the label that indicates where to resume running the code. This label includes the name of a method or a function followed by a colon. |
Example
The following example writes the numbers 1 through 6 and 8 through 10, and then the following string:
.Test
The use of the Continue statement after the if (i==7) statement prevents Siebel eScript from running the loop on the seventh iteration, but keeps running the loop:
var i = 0;
while (i < 10)
{
i++;
if (i==7)
continue;
document.write(i + ".Test");
}
Do While Statement
The Do While statement processes the code that the statement_block argument identifies repeatedly until the statement meets the value that the condition argument contains. The condition argument occurs at the end of the loop. Siebel eScript tests the condition only after the loop runs. A Do While loop always runs at least one time before Siebel eScript examines the condition.
Format
do
{
statement_block;
} while (condition)
The following table describes the arguments you can use with the Do While statement.
| Argument | Description |
|---|---|
statement_block |
One or more statements that Siebel eScript runs in the loop. |
condition |
An expression that describes the condition that Siebel eScript uses to repeat the loop. |
Example
The following example increments a value and prints the new value to the screen until the value reaches 100:
var value = 0;
do
{
value++;
Clib.sprintf(value);
} while( value < 100 );
For Statement
The For statement repeats a series of statements a fixed number of times. Siebel eScript does the following when it runs the For statement:
Evaluates the following expression:
counter = start
Does one of the following:
Condition is true or no conditional expression exists. It does the following work:
Runs the For statement.
Increments the counter.
Goes to For Statement.
Condition is false. It does the following work:
Exits the For statement.
Runs the code line that occurs immediately after the For statement.
Format
for ( [var] counter = start; condition; increment )
{
statement_block;
}
The following table describes the arguments for the For statement.
| Argument | Description |
|---|---|
counter |
A numeric variable for the loop counter. |
start |
The initial value of the counter. |
Usage
If the counter argument is not declared, then you must use the Var statement to declare it. Although it is declared in the For statement, the scope of the counter variable is local to the entire function that includes the for loop.
If you use multiple counters, then you must use a comma to separate each counter. For example:
for (var i = 1, var j = 3; i < 10; i++, j++) var result = i * j;
If you configure Siebel CRM to modify the value in the counter argument other than through the increment that occurs as a result of running the For statement, then your script might be difficult to maintain or debug.
Example
For an example of the For statement, see Evaluate Expression Method.
For In Statement
The For In statement loops through the properties of an associative array or object. You cannot use it with a nonassociative array. For more information, see About Associative Arrays.
You cannot write code that references a property that is marked with the DONT_ENUM attribute in a For In statement. The DONT_ENUM attribute is a predefined attribute that you cannot modify.
Format
for (LoopVar in object)
{
statement_block;
}
The following table describes the arguments for the For In statement. The statement block runs one time for every element in the associative array or property of the object.
| Argument | Description |
|---|---|
object |
An associative array or object:
|
LoopVar |
A variable that iterates over every element that resides in the associative array or property of the object. For each iteration of the loop, the LoopVar argument identifies the name of a property of the object or an element of the array. You can write code that references it with a statement that uses the following format:
|
Example
The following example creates an object named obj, and then uses the For In statement to read the object properties:
function PropBtn_Click ()
{
var obj = new Object;
var propName;
var msgtext = "";
obj.number = 32767;
obj.string = "Welcome to my world";
obj.date = "April 25, 1945";
for (propName in obj)
{
msgtext = msgtext + "The value of obj." + propName +
" is " + obj[propName] + ".\n";
}
TheApplication().RaiseErrorText(msgtext);
}
Running this code produces the following results:
The value of obj.number is 32767. The value of obj.string is Welcome to my world. The value of obj.date is April 25, 1945.
For an example of the For In statement used with an associative array, see About Associative Arrays.
Goto Statement
The Goto statement causes Siebel eScript to go to a specific point in a function. You can write code that directs Siebel eScript to go to any location in a function. It is recommended that you use a Goto statement only rarely because it makes it difficult to follow the code flow.
Format
goto label;
The following table describes the argument for the Goto statement.
| Argument | Description |
|---|---|
label |
Indicates the code line where Siebel eScript must resume running the code. You must place a label argument at the point where Siebel eScript must resume running the code. |
Example
The following example uses a label argument to loop continuously until the number is greater than 0:
function clickme_Click ()
{
restart:
var number = 10;
if (number <= 0 )
goto restart;
var factorial = 1;
for ( var x = number; x >= 2; x-- )
factorial = (factorial * x);
TheApplication().RaiseErrorText( "The factorial of " +
number + " is " + factorial + "." );
}
If Statement
The If statement tests a condition and proceeds depending on the result.
Format A
if (condition) statement;
if (condition)
{
statement_block;
}
[else if (condition)
{
statement_block;
}]
[else
{
statement_block;
}]
The following table describes the arguments for the If statement.
| Argument | Description |
|---|---|
condition |
An expression that evaluates to true or false. |
statement_block |
If the expression is:
|
Usage
If you require multiple statements, then use Format B.
The following example includes an If statement:
if ( i < 10 )
{
TheApplication().RaiseErrorText("i is less than 10.");
}
If Siebel eScript runs only a single If statement, then the curly brackets are not required. You can use them to clarify your code.
Else Clause
The else clause is an extension of the If statement. It allows you to run code if the condition in the If statement is false. The following example includes the else clause:
if ( i < 10 )
TheApplication().RaiseErrorText("i is less than 10.");
else
TheApplication().RaiseErrorText("i is not less than 10.");
If you require more than one If statement, then you must use curly brackets to group the statements. For example:
if ( i < 10 )
{
i += 10;
TheApplication().RaiseErrorText ("Original i was less than 10, and has now been
incremented by 10.");
}
else
{
i -= 5;
TheApplication().RaiseErrorText ("Original i was at least 10, and has now been
decremented by 5.");
}
This example includes an else clause in an If statement. This If statement tests for multiple conditions.
Example
The following example includes an else clause:
if ( i < 10 )
{
TheApplication().RaiseErrorText("i is less than 10.")
}
else if ( i > 10 )
{
TheApplication().RaiseErrorText("i is greater than 10.");
}
else
{
TheApplication().RaiseErrorText("i is 10.");
}
For another example, see Set Time Method.
For more information, see Switch Statement.
Switch Statement
The Switch statement makes a decision according to the value of a variable or expression. It chooses among alternatives when each choice depends on the value of a single variable. Siebel eScript does the following:
Evaluates the switch_variable argument.
Compares the values in the Case statements, and then does one of the following depending on if it finds a match:
Finds a match. Runs the statement block that follows the Case statement whose value matches the value in the switch_variable argument. It runs until it reaches the end of the statement block or until a Break statement causes it to exit the statement block.
Does not find a match. If a default statement exists, then it runs the default statement.
Usage
Make sure you end a Case statement with a Break statement.
Format
switch( switch_variable )
{
case value1:
statement_block
break;
case value2:
statement_block
break;
.
.
.
[default:
statement_block;]
}
The following table describes the arguments for the Switch statement.
| Argument | Description |
|---|---|
switch_variable |
The argument on whose value the course of action depends. |
valuen |
Values of the switch_variable argument, which are followed by a colon. |
statement_block |
One or more statements that Siebel eScript runs if the value of switch_variable argument is the value in the Case statement. |
Example
This example configures Siebel CRM to perform an action depending on an account type. In this example, a letter indicates the type of account:
switch ( key[0] )
{
case 'A':
I=I+1;
break;
case 'B':;
I=I+2
break;
case 'C':
I=I+3;
break;
default:
I=I+4;
break;
}
Siebel eScript runs code in the statement block until it encounters a Break statement. In this example, if you remove the Break statement that occurs after the I=I+2 statement, then Siebel eScript runs the following code:
I=I+2
I=I+3
For more information, see If Statement.
Throw Statement
The Throw statement causes Siebel eScript to stop running code if an error occurs.
Format
throw exception
The following table describes arguments for the Throw statement.
| Argument | Description |
|---|---|
exception |
An object in an error class. |
Usage
In the following example, the Throw statement stops the script after Siebel CRM displays an error message:
try
{
do_something;
}
catch( e )
{
TheApplication().Trace (e.toString()));
throw e;
}
If any error occurs while processing a statement in a try block, then Siebel eScript creates an exception. An outer catch block can handle this exception. For example, assume a section of code includes three levels of try catch blocks:
The innermost catch block includes a throw statement. An exception occurs.
The catch statement in the level two block catches this exception.
The catch statement in the level two block throws this exception to the level one block.
The catch block at level one handles this exception.
The following code illustrates this example:
try
{
do_something;
try
{
do_something;
}
catch(e)
{
TheApplication().Trace(e.toString());
throw e;
}
}
catch(e)
{
TheApplication().RaiseErrorText("Error Occurred "+e.toString());
}
You can write code that uses the RaiseErrorText method or the RaiseError method instead of the Throw statement to avoid receiving an unhandled exception error in the text that the Get Buffer Data method returns. If the Siebel Run-Time Engine creates an error message, or if the Throw statement creates an error message, then Siebel CRM adds the following text to the error message:
Unhandled Exception
Siebel CRM does this to distinguish an error message that the RaiseErrorText method or that the RaiseError method creates from an error that the Siebel Run-Time Engine creates or that the Throw statement creates.
For more information, see Get Buffer Data Method and Try Statement.
Try Statement
The Try statement processes an exception. It handles functions that can raise an exception, which is an error condition that causes the script to branch to another routine. It can include the following clauses:
Catch clause. Handles the exception. To raise an exception, you use the Throw statement. For more information, see Throw Statement.
Finally clause. Performs cleanup work. For example, removing object references.
You can write code that does the following to trap errors that a statement block creates:
Place code that must trap errors in a Try statement.
Follow the Try statement with a catch clause. You can write code that uses the exception_handling_block argument in this catch clause to process the exception.
Format
try
{
statement_block
}
catch
{
exception_handling_block
[throw exception]
}
finally
{
statement_block_2
}
The following table describes the arguments for the Try statement.
| Argument | Description |
|---|---|
statement_block |
A statement block that can create an error. |
exception_handling_block |
A statement block that processes the error. |
exception |
An error of a named type. |
statement_block_2 |
A statement block that Siebel eScript always runs unless the Try statement transfers control to elsewhere in the script. |
Example
The following example demonstrates the format of a Try statement that includes a catch clause. In this example, Siebel eScript continues to run the script after it displays the error message:
try
{
do_something;
}
catch( e )
{
TheApplication().RaiseErrorText(Clib.rsprintf(
"Something bad happened: %s\n",e.toString()));
}
The finally clause includes code that Siebel eScript must run before it exits the Try statement, regardless of if a catch clause stops running the script. You can write code that uses one of the following statements to exit a finally clause:
Goto
Throw
Return
The following example includes a finally clause. Siebel eScript continues running this code after the no_way statement. It ignores the Return statement:
try
{
return 10;
}
finally
{
goto no_way;
}
no_way: statement_block
While Statement
The While statement runs a section of code repeatedly until an expression evaluates to false. It does the following:
Examines the expression.
If the expression is true, then it does the following:
Runs the code in the statement block that occurs after the condition argument.
Repeats step 1.
If the expression is false, then Siebel eScript runs the code that occurs immediately after the statement block.
A while loop repeats until the value in the condition argument is false.
Format
while (condition)
{
statement_block;
}
The following table describes the arguments for the While statement.
| Argument | Description |
|---|---|
condition |
Includes a value that determines when to stop running the loop. You must enclose this argument in parentheses. |
statement_block |
One or more statements that Siebel eScript runs while the condition argument is true. |
Example
The following example includes a While statement that includes two lines of code in a statement block:
while(ThereAreUncalledNamesOnTheList() != false)
{
var name = GetNameFromTheList();
SendEmail(name);
}
With Statement
The With statement associates a default object with a statement block. It only applies to the code that resides in the statement block where the With statement occurs, regardless of how Siebel eScript enters or exits the statement block. If Siebel eScript exits a With statement, then the With statement no longer applies.
You cannot write code that uses a Goto statement or a label to enter or exit the middle of a statement block that resides in a With statement.
Format
with (object)
{
method1;
method2;
.
.
.
methodn;
}
The following table describes the arguments of the With statement.
| Argument | Description |
|---|---|
object |
An object where you must use multiple methods. |
method1, method2, methodn |
Methods that Siebel eScript runs with the object. The With statement prefixes each method with the object name and a period. |
Example
The following example includes a With statement:
var bcOppty;
var boBusObj;
boBusObj = TheApplication().GetBusObject("Opportunity");
bcOppty = boBusObj.GetBusComp("Opportunity");
var srowid = bcOppty.GetFieldValue("Id");
try
{
with (bcOppty)
{
SetViewMode(SalesRepView);
ActivateField("Sales Stage");
SetSearchSpec("Id", srowid);
ExecuteQuery(ForwardOnly);
}
}
finally
{
boBusObj = null;
bcOppty = null;
}
The code in the With statement block is equivalent to the following code:
bcOppty.SetViewMode(SalesRepView);
bcOppty.ActivateField("Sales Stage");
bcOppty.SetSearchSpec("Id", srowid);
bcOppty.ExecuteQuery(ForwardOnly);