™ AVEVA™ Scripting

Chapter 2 – QuickScript .NET functions

Topic
The topic within the application. Actual string or a string attribute.
Item
The item within the topic. Actual string or a string attribute.
Attribute
A string attribute, enclosed in quotation marks, that contains the requested value from the application, topic,
and item. Actual string or a string attribute.
Return value
Status is an integer attribute to which 1, -1, or 0 is written. The WWRequest() function returns 1 if the
application is running, the topic and item exist, and the value was returned successfully. It returns 0 if the
application is busy, and -1 if there is an error.
Remarks
Note: The three WWDDE functions Execute(), Poke() and Request() exist for legacy purposes.
The DDE value in the particular application, topic, and item is returned into Attribute.
The value is returned as a string into a string attribute. If the value is a number, you can then convert it using the
StringToIntg() or StringToReal() functions.
Important: Never do the following when using WWRequest() in synchronous scripts:
1. Loop scripts (call them over and over).
2. Call several of scripts in a row and in the same script.
3. Use scripts to call a lengthy task in another DDE application.
All three actions can be done in asynchronous scripts.
Example
The following statement requests a value from an Excel spreadsheet cell and converts the resulting string into a
value:
WWRequest("excel","[[Link]]sheet1","r1c1",Result);
Value=StringToReal(Result);
See also
StringToIntg()
StringToReal()

QuickScript .NET operators

The following QuickScript .NET operators require a single operand:

Operator Short description

~ Complement
- Negation
NOT Logical NOT
The following QuickScript .NET operators require two operands:

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 174
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

Operator Short description

+ Addition and concatenation

- Subtraction
& Bitwise AND
* Multiplication
** Power
/ Division
^ Exclusive OR
| Inclusive OR
< Less than
<= Less than or equal to
<> Not equal to
= Assignment
== Equivalency (is equivalent to); not supported for entire array
compares. Compare the arrays one element at a time using ==.

> Greater than

>= Greater than or equal to
AND Logical AND
MOD Modulo
OR Logical OR
SHL Left shift
SHR Right shift
The following table shows the precedence of QuickScript .NET operators:

Precedence Operator

1 (highest) ()
2 - (negation), NOT, ~
3 **
4 *, /, MOD
5 +, - (subtraction)

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 175
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

Precedence Operator

1 (highest) ()
6 SHL, SHR
7 <, >, <=, >=
8 ==, <>
9 &
10 ^
11 |
12 =
13 AND
14 (lowest) OR
The arguments of the listed operators can be numbers or attribute values. Putting parentheses around an
argument is optional. Operator names are not case-sensitive.

Parentheses ( )
Parentheses specify the correct order of evaluation for the operator(s). They can also make a complex expression
easier to read. Operator(s) in parentheses are evaluated first, preempting the other rules of precedence that
apply in the absence of parentheses. If the precedence is in question or needs to be overridden, use
parentheses.
In the example below, parentheses add B and C together before multiplying by D:
( B + C ) * D;

Negation ( - )
Negation is an operator that acts on a single component. It converts a positive integer or real number into a
negative number.

Complement ( ~ )
This operator yields the one's complement of a 32-bit integer. It converts each zero-bit to a one-bit and each
one-bit to a zero-bit. The one's complement operator is an operator that acts on a single component, and it
accepts an integer operand.

Power ( ** )
The Power operator returns the result of a number (the base) raised to the power of a second number (the
power). The base and the power can be any real or integer numbers, subject to the following restrictions:
• A zero base and a negative power are invalid.
Example: "0 ** - 2" and "0 ** -2.5"

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 176
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

• A negative base and a fractional power are invalid.

Example: "-2 ** 2.5" and "-2 ** -2.5"
• Invalid operands yield a zero result.
The result of the operation cannot be so large or so small that it cannot be represented as a real number.
Example:
1 ** 1 = 1.0
3 ** 2 = 9.0
10 ** 5 = 100,000.0

Multiplication ( * ), division ( / ), addition ( + ),subtraction ( - )

These binary operators perform basic mathematical operations. The plus (+) can also concatenate String
datatypes.
For example, in the data change script below, each time the value of "Number" changes, "Setpoint" changes as
well:
Number=1;
[Link] = "Setpoint" + Text(Number, "#" );
Where: The result is "Setpoint1."

Modulo (MOD)
MOD is a binary operator that divides an integer quantity to its left by an integer quantity to its right. The
remainder of the quotient is the result of the MOD operation. Example:
97 MOD 8 yields 1
63 MOD 5 yields 3

Shift left (SHL), shift right (SHR)

SHL and SHR are binary operators that use only integer operands. The binary content of the 32-bit word
referenced by the quantity to the left of the operator is shifted (right or left) by the number of bit positions
specified in the quantity to the right of the operator.
Bits shifted out of the word are lost. Bit positions vacated by the shift are zero-filled. The shift is an unsigned
shift.
Example 1
If Attribute2 = 00000111 (decimal 7)
Then the operation:
Attribute1 = Attribute2 SHL 3;
Results in:
Attribute1 = 00111000 (decimal 56)

Example 2
If Attribute2 = 00001011 (decimal 11)
Then the operation:

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 177
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

Attribute1 = Attribute2 SHR 2;

Results in:
Attribute1 = 00000010 (decimal 2)

Bitwise AND ( & )

A bitwise binary operator compares 32-bit integer words with each other, bit for bit. Typically, this operator
masks a set of bits. The operation in this example "masks out" (sets to zero) the upper 24 bits of the 32-bit word.
For example:
result = name & 0xff;

Exclusive OR (^) and inclusive OR ( | )

The ORs are bitwise logical operators compare 32-bit integer words to each other, bit for bit. The Exclusive OR
compare the status of bits in corresponding locations. If the corresponding bits are the same, a zero is the result.
If the corresponding bits differ, a one is the result. Example:
0 ^ 0 yields 0
0 ^ 1 yields 1
1 ^ 0 yields 1
1 ^ 1 yields 0
The Inclusive OR examines the corresponding bits for a one condition. If either bit is a one, the result is a one.
Only when both corresponding bits are zeros is the result a zero. For example:
0 | 0 yields 0
0 | 1 yields 1
1 | 0 yields 1
1 | 1 yields 1

Assignment ( = )
Assignment is a binary operator which accepts integer, real, or any type of operand. Each statement can contain
only one assignment operator. Only one name can be on the left side of the assignment operator.
Read the equal sign (=) of the assignment operator as "is assigned to" or "is set to."
Don't confuse the equal sign with the equivalency sign (==) used in comparisons.

Comparisons ( <, >, <=, >=, ==, <> )

Comparisons in IF-THEN-ELSE statements execute various instructions based on the state of an expression.

AND, OR, and NOT

These operators work only on discrete attributes. If these operators are used on integers or real numbers, they
are converted as follows:
• Real to Discrete: If real is 0.0, discrete is 0, otherwise discrete is 1.
• Integer to Discrete: If integer is 0, discrete is 0, otherwise discrete is 1.
If the statement is: "Disc1 = Real1 AND Real2;" and Real1 is 23.7 and Real2 is 0.0, Disc1 has 0 assigned to
it, since Real1 is converted to 1 and Real2 is converted to 0.

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 178
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

When assigning the floating-point result of a mathematical operation to an integer, the value is rounded to the
nearest integer instead of truncating it. This means that an operation like IntAttr = 32/60 results in IntAttr
having a value of 1, not 0. If truncation is needed, use the Trunc() function.

QuickScript .NET variables

Declare the QuickScript .NET variables before they can be used in QuickScript .NET scripts. Variables can be used
on both the left and right side of statements and expressions.
Local variables or attributes can be used together in the same script. Variables declared within the script body
lose their value after the script is executed. Those declared in the script body cannot be accessed by other
scripts.
Variables declared in the Declarations area maintain their values throughout the lifetime of the object that the
script is associated with.
Declare each variable in the script by a separate DIM statement followed by a semicolon. Enter DIM statements
in the Declarations area of the Script tab page. The DIM statement syntax is as follows:
DIM <variable_name> [ ( <upper_bound>
[, <upper_bound >[, < upper_bound >]] ) ]
[ AS <data_type> ];
where:

DIM Required keyword.

<variable_name> Name that begins with a letter (A-Z or a-z) and whose remaining characters
can be any combination of letters (A-Z or a-z), digits (0-9) and underscores
(_). The variable name is limited to 255 Unicode characters.

<upper_bound> Reference to the upper bound (a number between 1 and 2,147,483,647,

inclusive) of an array dimension. Three dimensions are supported in a DIM
statement, each being nested in the syntax structure. After the upper bound
is specified, it is fixed after the declaration. A statement similar to Visual
Basic’s ReDim is not supported.
The lower bound of each array dimension is always 1.
AS Optional keyword for declaring the variable’s datatype.

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 179
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

<data_type> Any one of the following 11 datatypes: Boolean, Discrete, Integer,

ElapsedTime, Float, Real, Double, String, Message, Time or Object.

Data_type can also be a .Net data_type like [Link] or a

type defined in an imported script library

If you omit the AS clause from the DIM statement, the variable, by default, is
declared as an Integer datatype. For example:

DIM LocVar1;

is equivalent to:

DIM LocVar1 AS Integer;

In contrast to attribute names, variable names must not contain dots. Variable names and the data type
identifiers are not case sensitive. If there is a naming conflict between a declared variable and another named
entity in the script (for example, attribute name, alias or name of an object leveraged by the script), the variable
name takes precedence over the other named entities. If the variable name is the same as an alias name, a
warning message appears when the script is validated to indicate that the alias is ignored.
The syntax for specifying the entire array is "[ ]" for both local array variables and for attribute references. For
example, to assign an attribute array to a local array, the syntax is:
locarr[] = [Link][];
DIM statements can be located anywhere in the script body, but they have to precede the first referencing script
statement or expression. If a local variable is referenced before the DIM statement, script validation done when
you save the object containing the script prompts you to define it.
The validation mentioned above occurs only when you save the object containing the script. This is not the script
syntax validation done when you select the Validate Script button.
Don't cascade DIM statements. For example, the following examples are invalid:
DIM LocVar1 AS Integer, LocVar2 AS Real;
DIM LocVar3, LocVar4, LocVar5, AS Message;
To declare multiple variables, enter separate DIM statements for each variable.
When used on the right side of an equation, declared local variables always cause expressions on the left side to
have Good quality. For example :
dim x as integer;
dim y as integer;
x = 5;
y = 5;
[Link] = 5;
[Link] = x;
[Link] = x+y;
In each case of [Link], quality is Good.
When you use a variable in an expression to the right of the operator, its Quality is treated as Good for the
purpose of data quality propagation.

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 180
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

You can use null to indicate that there is no object currently assigned to a variable. Using null has the same
meaning as the keyword "null" in C# or "nothing" in Visual Basic. Assigning null to a variable makes the variable
eligible for garbage collection. You may not use a variable whose value is null. If you do, the script terminates and
an error message appears in the logger. You may, however, test a variable for null. For example:
IF myvar == null THEN ...
It is not possible to pass attributes as parameters for system objects. To work around this issue, use a local
variable as an intermediary or explicitly convert the attribute to a string using an appropriate function call when
calling the system object.

Numbers and strings

Allowed format for integer constants in decimal format is as follows:
IntegerConst = 0 or [sign] <non-zero_digit> <digit>*;
where:
sign :: = + | -
non-zero_digit ::= 1-9
digit ::= 0-9
For example, an integer constant is a zero or consists of an optional sign followed by one or more digits. Leading
zeros are not allowed. Integer constants outside the range –2147483648 to 2147483647 cause an overflow error.
Prepending either 0x or 0X causes a literal integer constant to be interpreted as hexadecimal notation. The +/-
sign is supported.
The acceptable float for integers in hexadecimal is as follows:
IntegerHexConst = [<sign>] <0><x (or X)> <hexdigit>*
where:
sign ::= + or -
hexdigit ::= 0-9, A-F, a-f (only eight hexdigits [32-bits] are allowed)
Allowed format for floats is as follows:
FloatConst ::= [<sign>] <digit>* .<digit>+ [<exponent>;]
or
[<sign>] <digit>+ [.<digit>* [<exponent>]];
where:
sign ::= + or -
digit ::= 0-9 (can be one or more decimal digits)
exponent = e (or E) followed by a sign and then digit(s)
Float constants are applicable as values for variables of type float, real, or double. For example, float constants
don't take the number of bytes into account. Script validation detects an overflow when a float, real, or double
variable has been assigned a float constant that exceeds the maximum value.
If no digits appear before the period (.), at least one has to appear after it. If neither an exponent part nor the
period appears, a period is assumed to follow the last digit in the string.
If an attribute reference exists that has a format similar to a float constant with an exponent (such as "5E3"),
then use the Attribute qualifier, as follows:
Attribute("5E3")

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 181
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

Strings have to be surrounded by double quotation marks. They are referred to as quoted strings. The double-
double quote indicates a single double-quote in the string. For example, the string:
Joe said, "Look at that."
can be represented in QuickScript .NET as:
"Joe said, ""Look at that."""

QuickScript .NET control structures

QuickScript .NET provides five primary control structures in the scripting environment:
• IF … THEN … ELSEIF … ELSE … ENDIF
• FOR … TO … STEP … NEXT loop
• FOR EACH … IN … NEXT
• TRY ... CATCH
• WHILE loop

IF … THEN … ELSEIF … ELSE … ENDIF

IF-THEN-ELSE-ENDIF conditionally executes various instructions based on the state of an expression. The syntax is
as follows:
IF <Boolean_expression> THEN
[statements];
[ { ELSEIF
[statements] } ];
[ ELSE
[statements] ];
ENDIF;
Where Boolean_expression is an expression that can be evaluated as a Boolean.
Depending on the data type returned by the expression, the expression is evaluated to constitute a True or False
state according to the following table:

Data Type Mapping

Boolean, Discrete Directly used (no mapping needed).

Integer Value = 0 evaluated as False.
Value != 0 evaluated as True.
Float, Real Value = 0 evaluated as False.
Value != 0 evaluated as True.
Double Value = 0 evaluated as False.
Value != 0 evaluated as True.
String, Message Cannot be mapped. Using an expression that results in a string type as the
Boolean_expression results in a script validation error.

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 182
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

Data Type Mapping

Time Cannot be mapped. Using an expression that results in a time type as the
Boolean_expression results in a script validation error.

ElapsedTime Cannot be mapped. Using an expression that results in an elapsed time

type as the Boolean_expression results in a script validation error.

Object Using an expression that results in an object type. Validates, but at run
time, the object is converted to a Boolean. If the type cannot be converted
to a Boolean, a run-time exception is raised.
The first block of statements is executed if Boolean_expression evaluates to True. Optionally, a second block of
statements can be defined after the keyword ELSE. This block is executed if the Boolean_expression evaluates to
False.
To help decide between multiple alternatives, an optional ELSEIF clause can be used as often as needed. The
ELSEIF clause mimics switch statements offered by other programming languages. For example:
IF value == 0 Then
Message = "Value is zero";
ELSEIF value > 0 Then
Message = "Value is positive";
ELSEIF value < 0 Then
Message = "Value is negative";
ELSE
{Default. Should never occur in this example};
ENDIF;
The following approach nests a second IF compound statement within a previous one and requires an additional
ENDIF:
IF (X1 == 1) THEN
X1 = 5;
{ ELSEIF <X1 == 2> THEN
X1 = 10;
ELSEIF X1 == 3 THEN
X1 = 20 ;
ELSEIF X1 == 4 THEN
X1 = 30 };
IF X1 == 99 THEN
X1 = 0;
ENDIF;
ENDIF;
See Sample Scripts for more ideas about using this type of control structure.

IF … THEN … ELSEIF … ELSE … ENDIF and attribute quality

When an attribute value is copied to another attribute of the same type, the attribute’s quality is also copied.
This can be especially relevant when working with I/O attributes. For example, the following two statements
copy both value and quality:
me.Attr2 = me.Attr1;
[Link] = [Link];

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 183
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

If only the value needs to be copied and the attribute has the quality BAD, you can use a temporary variable to
hold the value. For example:
Dim temp as Integer;
temp = me.Attr1;
me.Attr2 = temp;
If there is a comparison such as Attr1 <> Attr2 and one of the attributes has the quality BAD, then the statements
within the IF control block are not executed. For example, assuming Attr1 has the quality BAD:
if me.Attr1<> me.Attr2 then
me.Attr2 = me.Attr1;
endif;
In this script, the statement me.Attr2 = me.Attr1 is not executed because Attr1 has the quality BAD and
comparing a BAD quality value with a good quality value is not defined/not possible.
The recommended approach is to first verify the quality of Attr1, as shown in the following example:
if(IsBad(me.Attr1)) then
LogMessage("Attr1 quality is bad, its value is not copied to Attr2");
else
if me.Attr1<> me.Attr2 then
me.AttrA2 = me.Attr1;
endif;
endif;
An alternative method of verifying quality is to use the "==" operator:
if Me.Attr1 == TRUE then
Or, you can add the "value" property to the simplified IF THEN statement:
if [Link] then
Your scripts will execute correctly if you verify the data quality using any of the above methods.

FOR … TO … STEP … NEXT loop

FOR-NEXT performs a function (or set of functions) within a script several times during a single execution of a
script. The general format of the FOR-NEXT loop is as follows:
FOR <analog_var> = <start_expression> TO <end_expression> [STEP <change_expression>];
[statements];
[EXIT FOR;];
[statements];
NEXT;
Where:
• analog_var is a variable of type Integer, Float, Real, or Double.
• start_expression is a valid expression to initialize analog_var to a value for execution of the loop.
• end_expression is a valid expression. If analog_var is greater than end_expression, execution of the script
jumps to the statement immediately following the NEXT statement.
This holds true if loop is incrementing up, otherwise, if loop is decrementing, loop termination occurs if
analog_var is less than end_expression.
• change_expression is an expression that defines the increment or decrement value of analog_var after
execution of the NEXT statement. The change_expression can be either positive or negative.

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 184
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

• If change_expression is positive, start_expression has to be less than or equal to end_expression or the

statements in the loop don't execute.
• If change_expression is negative, start_expression has to be greater than or equal to end_expression for
the body of the loop to be executed.
• If STEP is not set, then change_expression defaults to 1 for increasing increments, and defaults to -1 for
decreasing increments.
Exit the loop from within the body of the loop with the EXIT FOR statement.
The FOR loop is executed as follows:
1. analog_var is set equal to start_expression.
2. If change_expression is positive, the system tests to see if analog_var is greater than end_expression. If so,
the loop exits. If change_expression is negative, the system tests to see if analog_var is less than
end_expression. If so, program execution exits the loop.
3. The statements in the body of the loop are executed. The loop can potentially be exited via the EXIT FOR
statement.
4. analog_var is incremented by 1,-1, or by change_expression if it is specified.
5. Steps 2 through 4 are repeated.
FOR-NEXT loops can be nested. The number of levels of nesting possible depends on memory and resource
availability.

FOR EACH … IN … NEXT

FOR EACH loops can be used only with collections exposed by OLE Automation servers. A FOR-EACH loop
performs a function (or set of functions) within a script several times during a single execution of a script. The
general format of the FOR-EACH loop is as follows:
FOR EACH <object_variable> IN <collection_object >
[statements];
[EXIT FOR;];
[statements];
NEXT;
Where:
• object_variable is a dimmed variable.
• collection_object is a variable holding a collection object.
As in the case of the FOR … TO loop, it is possible to exit the execution of the loop through the statement EXIT
FOR from within the loop.

TRY ... CATCH

TRY ... CATCH provides a way to handle some or all possible errors that may occur in a given block of code, while
still running rather than terminating the program. The TRY part of the code is known as the try block. Deal with
any exceptions in the CATCH part of the code, known as the catch block.
The general format for TRY ... CATCH is as follows:
TRY
[try statements] ’guarded section

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 185
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

CATCH
[catch statements]
ENDTRY
Where:
tryStatements
Statement(s) where an error can occur. Can be a compound statement. The tryStatement is a guarded section.
catchStatements
Statement(s) to handle errors occurring in the associated Try block. Can be a compound statement.
Statements inside the Catch block may reference the reserved ERROR variable, which is a .NET [Link]
thrown from the Try block. The statements in the Catch block run only if an exception is thrown from the Try
block.
TRY ... CATCH is executed as follows:
1. Run-time error handling starts with TRY. Put code that might result in an error in the try block.
2. If no run-time error occurs, the script will run as usual. Catch block statements will be ignored.
3. If a run-time error occurs, the rest of the try block does not execute.
4. When a run-time error occurs, the program immediately jumps to the CATCH statement and executes the
catch block.
The simplest kind of exception handling is to stop the program, write out the exception message, and
continue the program.
The error variable is not a string, but a .NET object of [Link]. This means you can determine the
type of exception, even with a simple CATCH statement. Call the GetType() method to determine the
exception type, and then perform the operation you want, similar to executing multiple catch blocks.
Example:
dim command = new [Link];
dim reader as [Link];
[Link] = new [Link];
try
[Link] = "Integrated Security=SSPI";
[Link]="select * from [Link]";
[Link]();
reader = [Link]();
while [Link]()
[Link] = [Link](0);
LogMessage([Link]);
endWhile;
catch
LogMessage(error);
endtry;
if reader <> null and not [Link] then
[Link]();
endif;
if [Link] == [Link] then
[Link]();
endif;

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 186
 ™ AVEVA™ Scripting
Chapter 2 – QuickScript .NET functions

Note: The proceeding code example uses the [Link] method, which is deprecated. Instead of
this, use the SQLData Script Library for SQL Server queries.

WHILE loop
WHILE loop performs a function or set of functions within a script several times during a single execution of a
script while a condition is true. The general format of the WHILE loop is as follows:
WHILE <Boolean_expression>
[statements]
[EXIT WHILE;]
[statements]
ENDWHILE;
Where: Boolean_expression is an expression that can be evaluated as a Boolean as defined in the description of
IF…THEN statements.
It is possible to exit the loop from the body of the loop through the EXIT WHILE statement.
The WHILE loop is executed as follows:
1. The script evaluates whether the Boolean_expression is true or not. If not, program execution exits the loop
and continues after the ENDWHILE statement.
2. The statements in the body of the loop are executed. The loop can be exited through the EXIT WHILE
statement.
3. Steps 1 through 2 are repeated.
WHILE loops can be nested. The number of levels of nesting possible depends on memory and resource
availability.

© 2015-2026 AVEVA Group Limited or its subsidiaries. All rights reserved. Page 187