SoftSpy expressions
Introduction
This topic describes the types of expressions used in SoftSpy. These include expressions, simple expressions, and patterns. Subjects discussed in this section include expression results, operators, operator precedence and parentheses, and pattern matching.
This table lists SoftSpy expression types. A brief functional description is included with each type.
| expression | A combination of variables, constants, functions, and operators that produces a result when evaluated. |
|---|---|
| pattern | Specify a set of character string values. |
| simple expression | An expression used as a function argument or array subscript. |
Expressions are used in the COMMAND, ERROR, GO, IF, PRINT LINE, and SET commands.
Patterns are used in the HELP, LIST ACL, LIST MACRO, LOCATE, PRINT HELP, PRINT LIST, and UNWATCH commands.
Simple expressions are used as function arguments and as array subscripts.
Expression
Function
A combination of variables, constants, functions, and operators that produces a result when evaluated.
Syntax
Description
SoftSpy expressions consist of operands and operators. Operands include all variables allowed in a Model 204 User Language request. They also include constants, functions, fields, parameters, statistics, SoftSpy variables, and information on request compilation, quality assurance and resource usage. Operators include the large variety of different operators described in detail later in this section.
Up to five distinct operands are allowed in an expression. The number of operators allowed depends on the complexity of the expression, but at least five are always permitted.
Expression Results
Evaluation of an expression produces a single result. Normally the result is a character value, a numeric value, or a boolean (true or false) value. The value produced depends on the operators and operands that are used. Operands can have character, numeric, or boolean values. Similarly, operators can produce character, numeric, or boolean results.
Any numeric value can be viewed as a character string value. Character string values that represent numbers can be viewed as numeric values. If a character string value is considered numeric by the Model 204 $VNUM function then it is considered numeric by SoftSpy. Valid numeric strings can consist of leading blanks, followed by a sign, followed by blanks followed by decimal digits, followed by a decimal point and decimal digits, followed by trailing blanks.
Boolean values can be viewed as numeric and numeric values can be viewed as boolean. If the result of an expression is true then it has a numeric value of one, and if it is false it has a numeric value of zero. Similarly, if the numeric value is zero the boolean value is false, and if the numeric value is non-zero the boolean value is true.
When the result of an expression is a value the result is said to be KNOWN. Sometimes, however, the result of an expression is not a value. This can happen when operands used in the expression do not have values. For example, there is no value associated with a percent variable operand that is not defined in the current User Language request. Operands and expressions that do not have a value still have a result. Following is a summary of the different types of expression results:
| Type of Result | Meaning |
|---|---|
| INVALID | The expression consists of a single operand whose result is INVALID. Examples of situations that produce INVALID include invalid array subscripts and invalid function arguments. |
| KNOWN | The expression produced a result value. |
| NOT AVAILABLE | The expression consists of a single operand whose result is NOT AVAILABLE. Examples of situations that produce NOT AVAILABLE include references to operands in an environment where the reference is not permitted and references to operands that require optional SoftSpy features that are not available. |
| NOT PRESENT | The expression consists of a single operand whose result is NOT PRESENT. Examples of situations that produce NOT PRESENT include references to field occurrences that are not present in the current record and references to image items in an image that is not active. |
| UNDEFINED | The expression consists of a single operand whose result is UNDEFINED. Examples of situations that produce UNDEFINED include references to percent variables or global variables that are not currently defined. |
| UNKNOWN | The expression consists of multiple operands and did not produce a result value. This happens when one or more of the operands do not have a result value and the rules for evaluating the operators produce a result of UNKNOWN. |
SoftSpy Operators
SoftSpy provides a variety of different types of operators. They include arithmetic operators, character string operators, relational operators, boolean operators, and operators that test the type of an expression result.
- Arithmetic operators include addition, subtraction, multiplication, division, unary plus, and unary minus. Arithmetic operators have a precision consistent with User Language fixed percent variables which support fifteen significant digits.
- A character string operator that performs concatenation is provided.
- Relational operators that support alphabetic and numeric comparisons for greater than, less than, greater than or equal, less than or equal, equal, and not equal are available. Numeric comparisons only consider the integer portion of the numeric value.
- Logical or boolean operators that support AND, OR, and NOT are provided.
- Operators to determine if the type of a result is INVALID, KNOWN, NOT AVAILABLE, NOT PRESENT, UNDEFINED, or UNKNOWN are available.
| Operator | Description |
|---|---|
| * (multiply) | The values of the two expressions are multiplied together. If either expression does not have a numeric value, or if the product is outside the range ‑999,999,999,999,999 to 999,999,999,999,999, then the result is UNKNOWN. |
| / (divide) | The value of the first expression is divided by the value of the second expression. If either expression does not have a numeric value or if the second expression is zero then the result is UNKNOWN. |
| + (add) | The values of the two expressions are added together. If either expression does not have a numeric value, or if the sum is outside the range ‑999,999,999,999,999 to 999,999,999,999,999, then the result is UNKNOWN. |
| - (subtract) | The value of the second expression is subtracted from the value of the first expression. If either expression does not have a numeric value, or if the difference is outside the range ‑999,999,999,999,999 to 999,999,999,999,999, then the result is UNKNOWN. |
| + (unary) | The numeric value of the expression is returned. Any leading or trailing blanks are stripped and any fractional portion is dropped. If the expression is not numeric then the result is UNKNOWN. |
| - (unary) | The complement, or negative, of the numeric value of the expression is returned. If the expression is not numeric then the result is UNKNOWN. |
| WITH | The character values of the two expressions are concatenated together. If the result is more than 255 characters long then only the first 255 characters are used. If either expression is not KNOWN then the result is UNKNOWN. |
| [ IS ALPHA ] GT | True if the first expression is alphabetically greater than the second expression and false if it is less or equal. If either expression is not KNOWN then the result is UNKNOWN. |
| [ IS ALPHA ] > | Synonym for [ IS ALPHA ] GT. |
| [ IS ALPHA ] LT | True if the first expression is alphabetically less than the second expression and false if it is greater or equal. If either expression is not KNOWN then the result is UNKNOWN. |
| [ IS ALPHA ] < | Synonym for [ IS ALPHA ] LT. |
| [ IS ALPHA ] GE | True if the first expression is alphabetically greater than or equal to the second expression and false if it is less. If either expression is not KNOWN then the result is UNKNOWN. |
| [ IS ALPHA ] >= | Synonym for [ IS ALPHA ] GE. |
| [ IS ALPHA ] LE | True if the first expression is alphabetically less than or equal to the second expression and false if it is greater. If either expression is not KNOWN then the result is UNKNOWN. |
| [ IS ALPHA ] <= | Synonym for [ IS ALPHA ] LE. |
| [ IS ALPHA ] EQ | True if the two expressions are alphabetically equal and false if they are not equal. If either expression is not KNOWN then the result is UNKNOWN. |
| [ IS ALPHA ] = | Synonym for [ IS ALPHA ] EQ. |
| [ IS ALPHA ] NE | True if the two expressions are not alphabetically equal and false if they are equal. If either expression is not KNOWN then the result is UNKNOWN. |
| [ IS ALPHA ] ¬= | Synonym for [ IS ALPHA ] NE. |
| IS NUM GT | True if the first expression is numerically greater than the second expression and false if it is less or equal. If either expression does not have a numeric value then the result is UNKNOWN. |
| IS NUM > | Synonym for IS NUM GT. |
| IS NUM LT | True if the first expression is numerically less than the second expression and false if it is greater or equal. If either expression does not have a numeric value then the result is UNKNOWN. |
| IS NUM < | Synonym for IS NUM LT. |
| IS NUM GE | True if the first expression is numerically greater than or equal to the second expression and false if it is less. If either expression does not have a numeric value then the result is UNKNOWN. |
| IS NUM >= | Synonym for IS NUM GE. |
| IS NUM LE | True if the first expression is numerically less than or equal to the second expression and false if it is greater. If either expression does not have a numeric value then the result is UNKNOWN. |
| IS NUM <= | Synonym for IS NUM LE. |
| IS NUM EQ | True if the two expressions are numerically equal and false if they are not equal. If either expression does not have a numeric value then the result is UNKNOWN. |
| IS NUM = | Synonym for IS NUM EQ. |
| IS NUM NE | True if the two expressions are not numerically equal and false if they are equal. If either expression does not have a numeric value then the result is UNKNOWN. |
| IS NUM ¬= | Synonym for IS NUM NE. |
| AND | The boolean values of the two expressions are ANDed together. If both values are true then the result is true. If either value is false then the result is false. Otherwise the result is UNKNOWN. |
| OR | The boolean values of the two expressions are ORed together. If either value is true then the result is true. If both values are false then the result is false. Otherwise the result is UNKNOWN. |
| NOT | True if the expression is false and false if the expression is true. If the expression is not KNOWN then the result is UNKNOWN. |
| IS KNOWN | True if the result of the expression is KNOWN and false otherwise. |
| IS INVALID | True if the result of the expression is INVALID and false otherwise. |
| IS NOT AVAILABLE | True if the result of the expression is NOT AVAILABLE and false otherwise. |
| IS NOT PRESENT | True if the result of the expression is NOT PRESENT and false otherwise. |
| IS UNDEFINED | True if the result of the expression is UNDEFINED and false otherwise. |
| IS UNKNOWN | True if the result of the expression is UNKNOWN and false otherwise. |
Operator Precedence and Parentheses
The operators and operands of an expression are evaluated based on the precedence of the operators as shown in the table below. Operators listed in each precedence group are evaluated before operators listed in subsequent precedence groups. Operators within a precedence group are evaluated from left to right within the expression. The order of evaluation can be altered by using parentheses.
Precedence Operators
| Group 1 | IS KNOWN, IS INVALID, IS NOT AVAILABLE, IS NOT PRESENT, IS UNDEFINED, IS UNKNOWN |
| Group 2 | + (unary), ‑ (unary), NOT |
| Group 3 | * (multiply), / (divide) |
| Group 4 | + (add), ‑ (subtract) |
| Group 5 | WITH |
| Group 6 | GT, >, LT, <, GE, >=, LE, <=, EQ, =, NE, ¬= |
| Group 7 | AND |
| Group 8 | OR |
Examples
$A + 1 * %B DKWR OR DKRD "NAME=" WITH $NAME F.'FIRST NAME' IS NOT PRESENT %A(%B) IS NUM GT 5 'FORWARD ' WITH $COMMAND NOT $UPDATE ‑%B $A * ($B+$C)
See Also
COMMAND, ERROR, GO, IF, PRINT LINE, SET
Pattern
Function
Specify a set of character string values.
Syntax
Description
Patterns specify a set of character string values using pattern matching characters. Patterns can be optionally enclosed in either single or double quotes. If quotes are not used, a space or comma terminates the pattern. If an exclamation point precedes a quote mark, blank, or comma it does not terminate the pattern. Quote marks in a quoted pattern may be represented by either a pair of quotes, or by an exclamation point followed by
a quote mark.
Patterns can use special pattern matching characters to represent other characters. Except for pattern matching characters, the characters must match exactly any value that matches the pattern. Pattern matching characters and their meanings are shown below:
| Character | Effect |
|---|---|
| * | Match any set of characters |
| + | Match any single character |
| # | Match any single numeric character (0 to 9) |
| @ | Match any single alphabetic character (a to z, A to Z) |
| ! | The following character must match exactly even if it is a special pattern matching character |
Examples
* G.* CPU(*) 'DESCRIPTION LINE' DESCRIPTION! LINE %SCREEN:LINE# L@TBL %+++
See Also
HELP, LIST ACL, LIST MACRO, LOCATE, PRINT HELP, PRINT LIST, UNWATCH
Simple expression
Function
An expression used as a function argument or array subscript.
Syntax
operand
Description
A simple expression consists of a single operand or function. It must not use any parentheses and cannot be more than thirty characters long.
Function parameters and subscripts in percent variable operands, image item operands, and field operands must all be simple expressions.
To use a complex expression where only a simple expression is allowed, you must first resolve and assign the complex expression to a Softspy variable. You can then use the Softspy variable, which qualifies as a simple expression, in place of the complex expression.
Examples
SET $NAMELEN = $INDEX($NAME,' ')‑1 $SUBSTR($NAME, 1,$NAMELEN)
See Also
field operand, image item operand, percent variable operand