Statements

The information on this help page applies to both CXone Studio and Desktop Studio.

Statements define the actions a script takes when it executes. This includes creating variables, assigning new values, performing calculations, and making logical choices based on a given condition. Some statements only perform a task, such as assigning a value to a variable. Other statements affect the flow of the script. Statements are executed in a logical order, but that order can change each time the script runs.

Statements in snippets consist of one or more lines of code. A simple one-line statement might create a variable and assign a value to it, like this: 

ASSIGN firstName = "Beowulf"

A complex statement may have many nested groups of lines, like this: 

ASSIGN Names="Odin|Freya|Thor|Loki" ASSIGN SubCounter=1 FOREACH Name IN Names { IF Name = "Odin" | Name = "Freya" { ASSIGN NewNames[SubCounter]= "{Name}" ASSIGN SubCounter=SubCounter + 1 } }

The logical order of the execution of statement in a snippet can be changed if there is an error in the snippet. When an error occurs, the Snippet action immediately terminates. The remaining statements in the snippet aren't executed. Instead, an error message is saved in an _ERR variable indicating what the problem is.

Types of Statements

You can use the following types of statements in snippets: 

  • Declaration: Use declaration statements to declare, or create, new variables, objects, and functions.
  • Decision-Making: Use decision-making statements to have the snippet code select a task to perform based on the conditions you specify. You can use them to control the linear flow of what happens in the script.
  • Looping: Use looping statements to have the snippet perform a task or set of tasks repeatedly until the specified ending condition is met.
  • Other: These statements allow allow you to terminate functions, display results in the Snippet Editor window during debugging, and include web service proxy DLLs in your snippets.

Keywords

Keywords are commands that begin statements. They're pre-defined, reserved terms. The compiler recognizes the keyword and then performs the task associated with it.

Each type of statement that you can use in a snippet has a keyword associated with it. For example, to declare a variable, you can use the ASSIGN keyword. Or, to make a selection statement you can use the IF keyword. Both the statement and the keyword share the same name, so an IF statement uses the IF keyword.

The keywords available in the Snippet language are described along with the statement associated with each one. A complete list of keywords is also available.

Statement Syntax

All statements start with a keyword and are followed by words or code that define what the statement does. Each statement has its own syntax. The syntax summary section on this page describes how to read statement syntaxes.

Some statements require conditional code. This is code that sets a condition and defines what happens if the condition is or is not met. Conditional code can be a single statement or multiple statements. It must always be enclosed in curly braces ({ }), even if it's a single line. Conditional code is sometimes called a block.

When the compiler encounters a new line or an open curly brace, it recognizes the end of a statement. The placement of the curly braces is somewhat flexible. The following formats are all valid:


IF x=1 {TRACE "one" } 

IF x=1 {TRACE "one" } IF x=2 {TRACE "two" }
IF x=1 {
  TRACE "one"
}

IF x=1
{
  TRACE "one"
}

When the embedded code requires more than one statement, follow these rules: 

  • Place one statement per line.
  • If multiple statements are required, place them on separate lines. This makes it easier to read the code.
  • Embedded statements that require their own embedded code can take up multiple lines, following the valid formats for using curly braces.

Syntax Summaries

In the online help pages that cover each type of statement, each statement type has a syntax summary. The summary shows you the format that kind of statement uses. It shows you what elements are required and what's optional. It also demonstrates how the syntax elements must be nested.

The following table defines each element in the syntax summaries. Not all statements include every element. When deciphering a syntax summary, pay close attention to the nesting of elements.

Element

Details

 COMMAND

This is the name of the keyword to use with the statement. Replace COMMAND with the keyword for the statement you're creating.

Keywords are not case sensitive. For example: FOREACH is the same as foreach to the compiler. However, the Snippet action automatically converts all keywords to upper case the next time you open the snippet.

In the online help, keywords are always formatted in capital letters.

<required>

Angle brackets indicate a required element. The text inside the brackets indicates the kind of element, such as an expression, a variable, or a literal value.

For example, in a FOREACH statement syntax summary, there are two required elements: 

FOREACH <var> in <array> { ... [ BREAK]}

The angle brackets and the text inside them are never to be used literally in your script. Replace that portion with the code element it describes. For example, replace <expression>with an expression such as i = 0.

[optional]

Square brackets indicate an optional element. The text inside the brackets indicates the kind of element that you can use. For example, in the IF syntax summary, the optional ELSE clause is enclosed in square brackets: [ELSE { ... }.

If you use an optional element, it must appear in the location indicated in the syntax summary relative to the other elements.

The square brackets are never to be used literally in your script.

{ ... } Curly braces indicate a code block can be used.

Curly braces are different from the angle brackets and square brackets used in the syntax summary. Angle brackets and square brackets aren't meant to be included in your code, but curly braces must be included literally in your code. However, you should replace the ellipsis ( ... ) inside the curly braces in the syntax summary with Snippet statements.

Pipe ( | )

The pipe character indicates where you have a choice of what to include in the statement. For example, in the syntax summary for the ASSIGN statement, the pipe character indicates that you have a choice about enclosing the value in double quotes: 

ASSIGN <variable> = "<value>" | <value>

The explanation of the syntax explains the choice.

Ellipsis (...)

An ellipsis indicates one of two things:

  • Where code goes in a block, if found between curly braces.
  • A continuing pattern, if found between square brackets with a keyword.

An example of an ellipsis being used to indicate a continued pattern is found in the SELECT syntax summary:

SELECT <{ CASE <expression> [{ ... }] [CASE <expression> <{ ... }>] [CASE ...] [DEFAULT <{ ... }>] }>

The[CASE ...] indicates that you can continue adding as many CASE clauses as you need following the established pattern.

For example, the syntax summary for the IF statements used on this page is: 

IF <expression> <{ ... }>

This summary shows that:

  • The keyword is IF.
  • The next element is a required expression.
  • The last element is a required code block that must be enclosed in curly braces.

The syntax summary for SWITCH statements is more complex: 

SWITCH <var> <{CASE <literal> [{ ... }] [CASE <literal> [{ ... }]] [CASE ...] [DEFAULT [{ ... }]] }>

This summary shows that: 

  • The keyword is SWITCH.
  • The next element is a required variable name.
  • The code block is required and must contain a CASE clause with a literal value.
  • The required CASE clause can contain an optional code block.
  • The SWITCH statement's code block can include additional optional CASE clauses following the pattern established in the summary.
  • The SWITCH statement's code block can contain an optional DEFAULT clause with an optional code block.