EQUATE Statement

Declares a symbol to be equivalent to a DataBasic expression.

Syntax

EQU{ATE} symbol TO value {,symbol TO value} ...

EQU{ATE} symbol LIT{ERALLY} "litValue" {, symbol LIT{ERALLY} "litValue"} ...

See also $DEFINE statement.

Syntax Elements

Operation

When you compile your program, a pre-processor replaces all occurrences of each symbol with the corresponding value.

Comments

The EQUATE statement that defines a symbol must appear before the symbol is used in the program.

The EQUATE statement allows you to assign meaningful names to any of the above elements, thus improving the readability of your code. You can also place your symbol definitions at the beginning of you program or in a separate file item that can be referenced by the INCLUDE statement; this has the advantage of making them easy to find, should they need to be changed.

Symbols defined with the EQUATE statement cannot be undefined.

An EQUATE is terminated by an EOL character, comma or semi-colon; multi-line EQUATEs are not permitted.

Literals

If you use a symbol to represent a literal value, that value is compiled into the program, rather than accessing a variable location each time the program is run.

Defining a symbol to be equivalent to the CHAR function is similar - the symbol will be assigned the value returned by the function. For example, the statement:

EQUATE LF TO CHAR(10)

declares the symbol LF to represent the line feed character.

Variables

If you use a symbol to represent a variable or an array element, it represents a reference to the variable rather than its value. The two names are equivalent and can be used interchangeably to obtain the current value or to change the value of the variable.

Note also that if you equate a symbol to an array element, the computation of the element's address is done once at compile time, rather than each time the element is referenced at run time.

Examples:

EQU LINK TO ANCHOR
EQU PRICE TO PRODUCT(3)

Statements and Functions

Because your symbol is replaced before compilation, the statement or function you have specified operates in the same way as if you had typed it into your source code. In particular, any variables referred to in your expression will use the run-time values. For example, if you use the following EQUATE statement:

EQUATE VAR TO T.CODE<N>

the symbol VAR represents element N of dynamic array T.CODE. If T.CODE contains "John":@AM:"David":@AM:"Jane" and N is a variable that is set at run time, the value of VAR will be "John", "David" or "Jane", depending on the value of N.

Similarly, if the symbol LANG is declared to be equal to SYSTEM(35), it will hold the number of the language currently in use. If the language is subsequently changed, LANG will contain the new language number. Similarly, since SYSTEM(35) can be set though the SYSTEM statement or the ASSIGN statement, the language can be changed by assigning a new value to LANG.

Examples

EQUATE X TO Y

Equates symbol X to variable Y, so they may be used interchangeably within the program.

EQUATE PI TO 3.1416

Declares symbol PI to be equal to 3.1416.

EQU STARS TO "*****"

Declares symbol STARS to be equal to a string literal.

EQUATE ESC TO CHAR(27)

Declares symbol ESC to be equal to the character returned by CHAR(27).

EQU PART.NO TO ITEM(3)

Equates PART.NO to array element number 3 of ITEM.

COMMON A
EQUATE AA TO A

Equates symbol AA to COMMON variable A.

EQUATE CURRENCY TO SYSTEM(39)

Equates symbol CURRENCY to SYSTEM element 39 (money symbol).

EQU TODAY LITERALLY "DATE() 'DJ'"

Equates symbol TODAY to the current date, formatted as the Julian day (1-365 or 1-366 for a leap year).

EQU VM TO @VM

Equates symbol VM to a value mark (predefined symbol @VM).

EQUATE BEG.AUDIR TO TODAY:SVM

Equates symbol BEG.AUDIR to the value of TODAY concatenated with the value of SVM (where TODAY and SVM identify variables or symbols).

EQU HOSTNAME TO SYSTEM(22)<1>

Equates symbol HOSTNAME to element 1 of the dynamic array returned by the function SYSTEM(22).