Data types, operators, and expressions

Basic and advanced macro format

Your macro can be stored in either the basic macro format or the advanced macro format. When you record a macro using the host terminal, it is stored in the basic macro format. If you edit the macro and add support for variables and arithmetic expressions, your macro will be switched to the advanced macro format.

The basic macro format enables you to enter literal values, including integers, doubles, boolean (true or false), and strings.

In addition to the basic macro format functions, the advanced macro format offers these added functions:

Representation of strings and non-alphanumeric characters

You must write strings and the two special characters single quote (') and backslash (\) differently in the macro depending on whether you have chosen the basic macro format or the advanced macro format. Also, some characters that are ordinary characters in the basic macro format are used as operators in the advanced macro format, for example, the plus sign (+) and the greater than sign (>).

However, these rules affect only input fields located on editor tabs used to define screens (with the exception of the name), screen actions, and variables and types.

For other input fields, always use the rules for the basic macro format.

The following sections describe these differing rules.

Basic macro format rules

If you have chosen the basic macro format, use the following rules for input fields located on editor tabs used to define screens (with the exception of the name), screen actions, and variables and types:

Advanced macro format rules

If you have chosen the advanced macro format, use the following rules for input fields located on editor tabs used to define screens (with the exception of the name), screen actions, and variables and types:

Converting your macro to a different format

Macros in either format, basic or advanced, can be converted to the other format. The conversion process is automated when converting from basic format to advanced, but must be done manually when converting from the advanced to the basic format. Both conversions are described below.

Converting your basic format macro to the advanced format

You can easily convert your macro from the basic macro format to the advanced macro format, by selecting the Enable support for variables and arithmetic expressions check box on the Variables and Types tab of the macro properties in the VME or the Use Variables and Arithmetic Expressions in Macro check box on the Macro tab of the AME. As a result the Macro object does the following:

That is, the Macro object will find all the strings in your macro and surround them with single quotes, and the Macro object will change all occurrences of ' and \ to \' and \\. Also, any operator characters will be treated as operators.

Converting your advanced format macro to the basic format

Converting your macro from the advanced macro format to the basic macro format can be very difficult. There are no automatic conversions when you clear the option to use variables and arithmetic expressions. The only automatic result is that advanced features are disabled for the macro.

You must manually change, one at a time, all of the representations of strings and the two special characters back to the basic representations. You must also delete any instances where advanced features have been used in the macro. If you do not do so, you might encounter errors or unexpected results when you try to save or run the script. Any remaining advanced macro format operator characters will be treated as literal characters rather than as operators.

Standard data types

The Macro object supports the following standard data types:

These types are described in the following subsections.

Boolean data

The boolean values true and false can be written with any combination of uppercase and lower case letters (such as True, TRUE, FALSE, falsE, and so on).

Examples of fields that require a boolean value are the Entry screen, Exit screen, and Transient screen fields for a macro screen definition. Enter true to set the condition to true or false to set the condition to false.

Boolean values are not strings

Boolean values are not strings and are therefore never enclosed in single quotes. For example, whether you use the basic macro format or the advanced macro format, booleans are always written true and false, not 'true' and 'false'.

However, string values are converted to boolean values within a boolean context (see Conversion to boolean). Therefore with the advanced macro format you could enter the string 'true' within a boolean field because the macro editor would convert the string 'true' to the boolean value true.

Integers

Integers are written without commas or other delimiters. Examples:

10000
0
-140

Integer constants

The macro editor has a number of integer constants that are written using all uppercase characters. These values are treated as integers, not strings. Examples:

Doubles

Doubles are written without commas or other delimiters. Examples:

3.1416
4.557e5
-119.0431

Strings

A string is any sequence of characters and can include leading, trailing, or intervening blank characters. Strings in some input fields must be represented differently, depending on whether the macro has been set to use the basic macro format or the advanced macro format. See Representation of strings and non-alphanumeric characters.

The following examples use the advanced macro format representation:

'apple'
'User4'
'Total number of users'
'   This string has 3 leading blanks.'
'This string has 3 trailing blanks.   '

Here are the same examples using the basic macro format representation:

apple
User4
Total number of users
   This string has 3 leading blanks.
This string has 3 trailing blanks.   

Notice that with the basic macro format, trailing blanks are still allowed but are difficult to detect. If in doubt, see the representation of the string in the source view.

Fields

See Field variables.

The value null

The value null is a reserved word, not a string. When used in place of an object belonging to an imported Java class, it has the same meaning as it does in the Java language.

Do not use null to signify an empty string. To signify an empty string, use a pair of single quotes ('') in the advanced macro format, or nothing at all in the basic macro format. If you use the value null in a string context (for example, by assigning it to a string variable), then the macro editor or the macro runtime will convert the value null to the string 'null'.

Arithmetic operators and expressions

In order to use arithmetic expressions you must first select the Enable support for variables and arithmetic expressions check box on the Variables and Types tab of the macro properties in the VME or select the Use Variables and Arithmetic Expressions in Macro check box on the Macro tab of the AME. For more information, see Representation of strings and non-alphanumeric characters).

The arithmetic operators are shown in Table 2.

Table 2. Arithmetic operators
Operator Operation
+ Addition
- Subtraction
* Multiplication
/ Division
% Modulo

In an arithmetic expression the terms are evaluated left to right. The order of precedence of the operators is: *, /, %, +, -. For example, the result of the following expression is 8:

4 * 2 + 16 / 8 - 1 * 2

You can use parentheses to indicate the order in which you want expressions to be evaluated:

(4 * 2) + (16 / 8) - (1 * 2)    evaluates to 8
but
4 * (( 2 + 16) / (8 - 1)) * 2   evaluates to 20.571

Using arithmetic expressions

You can use an arithmetic expression almost anywhere that you can use an arithmetic value. Examples:

String concatenation operator (+)

You can use the string concatenation operator plus symbol (+) only if you use variables and arithmetic expressions in your macro. See Basic and advanced macro format.

You can write a string expression containing multiple concatenations. The following examples use the string representation required for the advanced format (see Representation of strings and non-alphanumeric characters).

Expression:               Evaluates to:

'Hello ' + 'Fred' + '!'   'Hello Fred!'
'Hi' 'There'              (Error, a + operator is required to concatenate strings)
'Hi' + 'There'            'HiThere'

Conditional and logical operators and expressions

The conditional operators are shown in Table 3.

Table 3. Conditional operators
Operator Operation
== Equal
!= Not equal
> Greater than
< Less than
>= Greater than or equal
<= Less than or equal

The logical operators are shown in Table 4.

Table 4. Logical operators
Operator Operation
&& AND
|| OR
! NOT

If you are entering && in an HTML or XML editor you might have to enter &amp;&amp;

In a conditional expression the terms are evaluated left to right. The order of precedence of the operators is the same order in which they are listed in the tables above. You can use parentheses to indicate the order in which you want expressions to be evaluated. Examples:

Expression:                  Evaluates to:

(4 > 3)                      true
!(4 > 3 )                    false
(4 > 3) && (8 > 10)          false
(4 > 3) || (8 > 10)          true

A conditional expression can contain arithmetic expressions, variables, and calls to methods of imported Java classes.

Conditional and logical operators can be used in only two contexts:

Automatic data type conversion

Effect of context

If an item of data belongs to one standard data type (boolean, integer, double, or string) but the context requires a different standard data type, then when the data is evaluated (either when the macro editor saves the data or when the macro runtime plays the macro) it is automatically converted to the standard data type required by the context, if possible.

Examples of context are:

However, if the data cannot be converted to the new data type (for example, the string 123apple cannot be converted to an integer), then an error occurs. The macro editor displays an error message. The macro runtime stops the macro playback and displays an error message.

The following subsections discuss the conversions that can occur for each standard data type.

Conversion to boolean

The string 'true' (or 'TRUE', 'True', and so on) in a boolean context is converted to boolean true. Any other string in a boolean context (including 'false', '1', 'apple', and any other) is converted to boolean false.

'true' (in an input field that requires a boolean)  converts to true
'apple' (in an input field that requires a boolean)  converts to false

Conversion to integer

A string in valid integer format and occurring in an integer context converts to integer.

'4096'                 converts to       4096
'-9'                   converts to       -9

Conversion to double

A string in valid double format occurring in a double context converts to double.

'148.3'                 converts to 148.3

An integer combined with a double results in a double:

10 +  6.4             evaluates to 16.4

Conversion to string

A boolean, integer, or double in a string context converts to a string. (The boolean values true and false are not strings. See Boolean data.) The following values, when specified for an input field requiring a string value (such as the String field of an Input action), will evaluate to the specified result.

'The result is ' + true                         evaluates to 'The result is true'
FALSE (in an input field that requires a string) converts to 'false'
'The answer is ' + 15                           evaluates to 'The answer is 15'
22 (in an input field that requires a string)   converts to  '22'
14,52 (in an input field that requires a string) evaluates to'14,52'

Conversion errors

If the context requires a conversion but the format of the data is not valid for the conversion then the macro editor displays an error message. For example, typing '123apple' into the Row field of an Input action will cause an error message to be displayed and the previous value will be restored.

Equivalents

Any context that accepts an immediate value of a particular standard data type also accepts any entity of the same data type.

For example, if an input field accepts a string value, such as 'Standard Dialog', it also accepts:

Similarly, if an input field accepts a boolean value (true or false), it also accepts:

Recognizing this flexibility in the macro facility will help you write more powerful macros.

Significance of a negative value for a row or column

In the String descriptor and in several other descriptors and actions, a negative value for a row or column indicates an offset from the last row or the last column of the host terminal. The macro runtime calculates the row or column location as follows:

actual row    = (number of rows in text area)    + 1 + (negative row offset)
actual column = (number of columns in text area) + 1 + (negative column offset)

For example, if the host screen has 24 rows of text then a row coordinate of -1 indicates an actual row coordinate of 24 (calculated as: 24 + 1 - 1). Similarly if the host screen has 80 columns of text then a column coordinate of -1 indicates an actual column coordinate of 80 (calculated as 80 + 1 - 1).

The row calculation above ignores the OIA row. For example, if the host screen has 25 rows, it has only 24 rows of text.

The advantage of this convention is that if you want to specify a rectangle at the bottom of the host terminal, then this calculation gives the right result whether the host screen has 25, 43, or 50 rows. Similarly, if you want to specify a rectangle at the right side of the host terminal, then this calculation gives the right result whether the host screen has 80 columns or 132 columns.

Table 5 and Table 6 show the results for a few calculations:

Table 5. Negative value for row
Negative value for row: Actual value in host terminal with 24 rows of text (OIA row is ignored): Actual value in host terminal with 42 rows of text (OIA row is ignored): Actual value in host terminal with 49 rows of text (OIA row is ignored):
-1 24 42 49
-2 23 41 48
-3 22 40 47
Table 6. Negative value for column
Negative value for column: Actual value in host terminal with 80 columns: Actual value in host terminal with 132 columns:
-1 80 132
-2 79 131
-3 78 130

Whether you use this convention or not, you should at least remember that a rectangular area with coordinates of (1,1) and (-1,-1) means the entire text area of the host terminal.