Expressions

An expression is a constant, a variable, an array element, a function or a combination of these with one or more operators. The result of an expression will be an integer, a numeric or a text value. Operators are discussed below. Expressions can be used wherever constants can be used: in assignments, in comparisons, as part of a larger expression or as an argument in an ADAPL function.

Arithmetic expressions

If a calculation consists of a number of different expressions (e.g. 2 + 3 * 2 / 10 - 5), Collections will evaluate them in a fixed order. This order corresponds with the standard arithmetic order: exponentiation, multiplication, division, integer modulus, addition, and subtraction. The table below shows the operators that can be used in numeric expressions, in order of evaluation:

Operator

Description

( )

Round brackets (parentheses) enclose an independent expression

^

Exponentiation

*

Multiplication

/

Division (requires numerical values or variables to produce a numerical result)

\

Integer modulus (the remainder of a division)

+

Addition

-

Subtraction

The following functions with a numeric or integer result are available in arithmetic expressions:

abs()

Absolute value of a number

asc()

ASCII value of a character

datdif()

Number of days between two dates

dayofweek()

Gives the day number for the date (0 is Sunday ... 6 is Saturday)

instr$()

Position of a character in a string

int()

The whole (integer) part of a value

len()

The actual length of a character string

max()

The maximum value of a series of values

min()

The minimum value of a series of values

mod()

The remainder from the division of two values

ndays()

The number of days until (negative value) or since the beginning of 1900 (positive value)

repcnt()

The number of occurrences of a tag

repfind()

Searches for a text string in a tag

repmax()

The maximum value in a tag

repmin()

The minimum value in a tag

repsum()

The total of occurrences of a tag

rinstr$()

The position of a character in a string

round()

The rounded value of a number

sqrt()

The square root of a number

val()

The numeric value of a character string

Text expressions

One operator is available in ADAPL for text expressions: +. The ‘plus’ sign concatenates text strings. For example:

ERRORM 'He said:' + '''' + 'Hello!' + '''' + '.'
* four consecutive quotes as separate (sub) string are
* required to actually include (display) only one quote (see also ADAPL constants).

The result of this instruction appears on screen: He said: 'Hello!'.

The following functions with a text result are available for text expressions:

after$()

Returns a substring to the right of indicated character(s)

before$()

Returns a substring to the left of indicated character(s)

chr$()

Returns a character from the ASCII table

cvt$$()

Converts from/to upper case

date$()

Returns the system date as a string

getvar()

Reads the contents of a global system variable

isolatintohtml$()

Converts a string from Isolatin to HTML

jstr$()

Justifies or centres a line

left$()

The left part of a character string

len()

The actual length of a character string

mid$()

Any part of a character string

name$

Changes ‘surname, first name’ to ‘first name surname’

recdate$()

Input or mutation date or time as a character string

right$()

The right-hand part of a character string

round$()

The rounded value of a number

str$()

Converts a value to a character string

string$()

Generates a string of equal characters

tag2field$()

Returns the name of the tag as entered in the database setup. If no name is filled in there, the tag will be returned

text$()

Reads line from text file

time$()

The system time as a character string

trim$()

Removes leading and/or trailing blanks

user$()

User name or user number as character string

whatdate()

Returns a computed date as a character string

Logical expressions

Logical expressions are expressions that contain logical operators and operators for comparison. The result of a logical expression is either TRUE or FALSE. These values are defined numerically: 0 represents FALSE, any other value represents TRUE.

Integers and numerics are interchangeable for logical expressions. With text comparisons, the value of the logical expression is numeric.

ADAPL allows the following operators for logical expressions:

Operator

Description

Note

( )

Round brackets embed an independent expression

 

=

Equals.

String comparisons are always case-sensitive.

<

Less than or alphabetic precedence

Number values obtained from database tags must always first be converted to numerics (VAL) and then possibly to integers (INT) before they can be compared as numbers or be used in calculations.

=< or <=

Less than or equal to

>

Greater than or alphabetic succession

=> or >=

Greater than or equal to

<> or ><

Does not equal

AND

TRUE if both expressions are TRUE

 

NOT

Reverses the result of the expression following it

 

OR

TRUE if at least one out of two expressions is TRUE

 

XOR

TRUE if one expression is TRUE and the other is FALSE

 

Tag indirection

Tag indirection means that the content of a text variable is treated as if it were a database tag. Typically, tag indirection is used when the database tags you wish to use in your code, are also ADAPL reserved words or commands, like for instance the do tag in the PEOPLE database: only by entering the tag as a string (in between quotes) into the code, ADAPL won't treat it as a command.
The indirection operator, the exclamation mark, is placed immediately before this variable, to use this functionality. To access subsequent elements of the tag, simply add the required occurrence number, enclosed in round or square brackets, to the name of the string.

The following piece of code displays the first line of the title of a book:

text tag_var[2]
tag_var = 'ti' /* title
errorm !tag_var[1]

With a dataset that has been opened using FACS, the FACS name of the dataset must be included in the text variable before the tag, e.g.:

text domain_tag[15]
domain_tag = 'PEOPLE do'
errorm !domain_tag[1]

This piece of code will display the first occurrence of the domain field in the PEOPLE database.
Note that a FACS declaration cannot contain the tag do, nor can you use tag indirection inside the FACS declaration so you have to use the method shown above.
Also note that all tags in an opened FACS database addressed in above shown way, no longer have to be specified in the FACS declaration.

Reading a FACS database (with the read command) using tag indirection is possible as well, but if that tag is an enumerative field too, then searching will only yield results if the Collections interface language is English. So the following only works in English and therefor shouldn't be used at all:

text domain_tag[15]
domain_tag = 'SUPPLIER do'
read SUPPLIER using !domain_tag = 'SUPPLIER'

The indirection operator may also appear in a different context, to directly address a tag in a record buffer, including tags which are also reserved words in ADAPL. Records buffers include FACS-declared databases and adlib_lite (which contains the contents or a currently edited record). For example, to retrieve the contents of the do tag from the currently edited record and display it in an error message:

errorm adlib_lite!do

Another example for the case in which a FACS database People has been declared:

if (enumval$(People!do, People!do, -1) = 'AUTHOR'){ … }

Sequence of evaluation in an expression

In the case of compound expressions, Collections will evaluate the various expressions in a fixed sequence. This sequence is based on the standard arithmetic sequence: exponentiation, multiplication, division, addition, and subtraction. Collections adheres to the following order:

1. tag indirection
2. unary minus (the minus sign of a negative value)
3. functions
4. exponentiation
5. multiplication and division
6. modulus
7. addition and subtraction.

In the event of equal priority, ADAPL will evaluate an expression from left to right.

Expressions and functions can occur within other expressions and functions if they are embedded in round brackets (). The evaluation always begins with the expression in the innermost round brackets, then working outwards. If expressions are used for comparisons, the expressions are evaluated before the comparison is carried out.

The sequence of evaluation in logical expressions is:

1. tag indirection and arithmetic evaluation
2. comparative operators
3. logical operators.

Independent expressions which are embedded in round brackets are evaluated first.