Data types, operators, and expressions

 

+
Search Tips   |   Advanced Search

 

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 use the Advanced Macro Editor to add advanced features, your macro will be switched to the advanced macro format.

The basic macro format:

• Allows you to enter literal values, including integers, doubles, boolean (true or false), and strings.

In contrast the advanced macro format:

• Likewise allows you to enter literal values, including integers, doubles, boolean (true or false), and strings.
• Allows string concatenation using the '+' string operator.
• Allows arithmetic expressions.
• Allows conditional expressions.
• Allows variables.
• Allows imported Java variable types and methods

 

Representation of strings and special characters, treatment of operator 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.

However, these rules affect only input fields located on the following tabs:

• Description tab of the Screens tab
• Actions tab of the Screens tab
• Variables tab

The input fields that are affected on these tabs are as follows:

• Of course, text input fields on the surface of the tab, such as the Number of Fields text input field on the Field Counts and OIA window of the Description tab.
• But also, the text input field in the window that pops up when you select the <Expression> entry in a listbox on the tab, such as the <Expression> entry in the Ignore Case listbox on the String descriptor window.

For input fields on all other tabs than those listed above, always use the rules for the basic macro format.

The following two sections describe these differing rules.

In the basic macro format, rules for representation of strings, etc.

If you have chosen the basic macro format, use the following rules for input fields on the Description tab, Actions tab, and Variables tab:

• Strings must be written without being enclosed in single quotes. Examples:

  apple
  banana
  To be or not to be
  John Smith

• The single quote (') and the backslash (\) are represented by the characters themselves without a preceding backslash. Examples:

  New Year's Day
  c:\Documents and Settings\User

• The following characters or character sequences are not treated as operators: +, -, *, /, %, ==, !=, >, <, >=, <=, &&, ||, !.

In the advanced macro format, rules for representation of strings, etc.

If you have chosen the advanced macro format, use the following rules for input fields on the Description tab, Actions tab, and Variables tab:

• All strings must be written enclosed in single quotes. Examples:

  'apple'
  'banana'
  'To be or not to be'
  'John Smith'

• The single quote (') and the backslash (\) are represented by the characters themselves preceded by a backslash. Examples:

  'New Year\'s Day'
  c:\\Documents and Settings\\User

• The following characters or character sequences are treated as operators:

  • String concatenation operators: +
  • Arithmetic operators: +, -, *, /, %
  • Conditional operators: ==, !=, >, <, >=, <=
  • Logical operators: &&, ||, !

 

Converting your macro to a different format

Converting your macro to the advanced macro format

You can easily convert your macro from the basic macro format to the advanced macro format, just by checking the "Use Variables and Arithmetic Expressions in Macro" checkbox on the Macro tab. As a result the Macro object does the following:

• It enables all the advanced features for your macro.
• It automatically converts, in all input fields where conversion is required, all the strings in your macro and all occurrences of the two special characters single quote (') and backslash (\) from their basic representations to their advanced representations.

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 macro to the basic macro 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 "Use Variables and Arithmetic Expressions in Macro" checkbox. The only automatic result is that advanced features are disabled for the macro.

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

 

Standard data types

The Macro object supports the following standard data types:

• boolean
• integers
• doubles
• strings

These types are described in the subsections below.

 

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).

An example of a input field that requires a boolean value is the Entry Screen field on the General tab of the Screens tab. Enter true to set the condition to true or false to set the condition to false.

Boolean values are not strings

The boolean values are not strings and therefore never need to be enclosed in single quotes. To repeat, 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 in a boolean context (see Conversion to boolean). Therefore with the advanced macro format you could enter the string 'true' in 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:

• NOTINHIBITED
• FIELD_PLANE
• COLOR_PLANE

 

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 special characters, treatment of operator characters.

The following examples use the representation for the advanced macro format:

'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 representation for the basic macro format.

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

To use arithmetic expressions first check the "Use Variables and Arithmetic Expressions in Macro" checkbox on the Macro tab (see Representation of strings and special characters, treatment of operator characters).

 

Operators and expressions

The arithmetic operators are:

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 :

4 * 2 + 16 / 8 - 1 * 2

is 8. 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

 

Where arithmetic expressions can be used

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

• As a parameter for a screen. For example,
  • To specify a recognition limit for a screen.
  • To specify a pause time for a screen.

• As a parameter for a descriptor. For example,

  • To specify a row or column in cursor descriptor.
  • To specify the number of fields in a numeric field count descriptor.
  • To specify a row, column, or attribute value in an attribute descriptor.
  • As a term in a conditional descriptor.

• As a parameter in an action. For example,

  • To specify a row or column in a mouse click action.
  • As the number of milliseconds in a pause action.
  • To specify a value in a variable update action.
  • As a term in a conditional action.

• As an initial value for a variable.

 

String concatenation operator (+)

Use the string concatenation operator '+' only if you check the "Use Variables and Arithmetic Expressions in Macro" checkbox on the Macro tab. See Basic and advanced macro format.

 

Operators and expressions

The string operators are shown in the table below.

Operator	Operation
+	Concatenate

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 special characters, treatment of operator 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:

Operator	Operation
==	Equal
!=	Not equal
>	Greater than
<	Less than
>=	Greater than or equal
<=	Less than or equal

The logical operators are:

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. 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

 

Conditional expression can include complex terms

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

 

Where conditional expressions can be used

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

• The Condition field of a conditional descriptor
• The Condition field of a conditional action

 

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 else 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:

• The Condition field of a Condition descriptor (expects a boolean value)
• The Value field of a Variable update action when the variable is a field variable (expects a location string)
• The Row value of an Input action (expects an integer value)

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. (Remember, the boolean values true and false are not strings. See Boolean data.)

'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'
('4.5' == .45e1)                                evaluates to true
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. If the error occurs while a macro is playing then the macro runtime display an error message and terminates the macro with a run-time error.

'123apple'       in an integer context    Error
'22.7peach'      in a double context      Error

 

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:

• An expression that evaluates to a string.
• A value that converts to a string.
• A string variable.
• A call to an imported method that returns a string.

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

• An expression that evaluates to a boolean value.
• A value that converts to a boolean value.
• A boolean variable.
• A call to an imported method that returns a boolean.

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 is 25 rows high, 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.

The following tables shows the results for a few calculations:

Negative value for row:	Actual value in host terminal with 24 columns of text (OIA row is ignored):	Actual value in host terminal with 42 columns of text (OIA row is ignored):	Actual value in host terminal with 49 columns of text (OIA row is ignored):
-1	24	42	49
-2	23	41	48
-3	22	40	47

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 make use of this convention or not, at least remember that a rectangular area with coordinates of (1,1) and (-1,-1) means the entire text area of the host terminal .

 

Home