References the value of a preprocessor name in any 4GL or preprocessor expression.
SYNTAX
Enter the braces ({}) as shown; they do not represent syntax notation in this description.
&preprocessor-name
Expands the name, preprocessor-name, to its defined value. You can define preprocessor names using either the &GLOBAL-DEFINE Preprocessor Directive or the
&SCOPED-DEFINE Preprocessor Directive. Progress also provides a set of built-in preprocessor names that you can reference for a variety of session information. Table 3 lists each built-in preprocessor name with its description.
Interfaces OS SpeedScript
All All Yes
{ &preprocessor-name }
Table 3: Built-in Preprocessor Names (1 of 2)
The Preprocessor
Name ... Expands to an Unquoted String ...
BATCH-MODE Equal to "yes" if the Batch (-b) startup parameter was used to start the client session. Otherwise, it expands to "no".
FILE-NAME That contains the name of the file being compiled.1 If you want only the name of the file as specified in the { } Include File Reference, the RUN statement, or the COMPILE statement, use the argument reference {0}.
LINE-NUMBER That contains the current line number in the file being compiled. If you place this reference in an include file, the line number is calculated from the beginning of the include file.
OPSYS That contains the name of the operating system on which the file is being compiled. The OPSYS name can have the same values as the OPSYS function. The possible values are referenced, the value increases by 1. To store the value of a reference to SEQUENCE, you must define another preprocessor name as {&SEQUENCE} at the point in your code you want the value retained.
WINDOW-SYSTEM That contains the name of the windowing system in which the file is being compiled. The possible values include
"MS-WINDOWS", “MS-WIN95", and ”TTY".3
1 When running the source code of a procedure file loaded into the Procedure Editor or the AppBuilder, {&FILE-NAME} expands to a temporary filename, not the name of the file under which the source code might be saved.
2 Progress supports an override option that enables applications that need to return the value of MS-DOS for all Microsoft operating systems to do so. For example, if you do not want the value WIN32 to be returned when either Windows 95 or Windows NT operating systems are recognized, you can override this return value by defining the Opsys key in Startup section of the current environment, which can be in the registry or in an initialization file. If the Opsys key is located, the OPSYS function returns the value associated with the Opsys key on all platforms.
3 Progress supports an override option for the &WINDOW-SYSTEM preprocessor name that provides backward compatibility. This option enables applications that need the WINDOW-SYSTEM preprocessor name to return the value of MS-WINDOWS for all Microsoft operating systems to do so.
To establish this override value, define the WindowSystem key in Startup section of the current environment, which can be in the registry or in an initialization file. If the WindowSystem key is located, the WINDOW-SYSTEM preprocessor name returns the value associated with the WindowSystem key on all platforms.
Table 3: Built-in Preprocessor Names (2 of 2)
The Preprocessor
Name ... Expands to an Unquoted String ...
Table 4 lists the additional built-in preprocessor names that apply to SpeedScript.
EXAMPLES
The procedure r-prprc1.p shows how you can reference a built-in preprocessor name and include it in a character string.
Table 4: SpeedScript Built-in Preprocessor Names
The Preprocessor
Name ... Expands to an Unquoted String ...
DISPLAY DISPLAY {WEBSTREAM}
END The {&END} reference is useful as a visible statement terminator for {&OUT} statement and {&DISPLAY}
statement sequences with a large number of output terms (expressions).
OUT PUT {WEBSTREAM} UNFORMATTED
WEBSTREAM STREAM WebStream. The Agent control program,
install-path/src/web/objects/web-disp.p, opens this stream at startup as the common Web stream (OUTPUT {&WEBSTREAM} TO “WEB”:U.).
r-prprc1.p
MESSAGE "The current operating system is" "{&OPSYS}."
VIEW-AS ALERT-BOX.
The procedure r-prprc2.p shows how to capture the value of a {&SEQUENCE} reference. In this example, {&SEQUENCE} is referenced three times, once each to assign its value to wvar (0) and xvar (1) at run time. The third reference defines the preprocessor name Last-Value with the value 3. Last-Value is assigned unchanged to both yvar and zvar, each of which take the value 3 at run time.
The procedure r-prprc3.p shows how preprocessor names override compile-time arguments.
In this example, r-prprc3.p defines the preprocessor name My-Name as "Daniel". It then passes the compile-time argument My-Name, with the value "David", to the include file
r-prprc3.i, which in turn defines a preprocessor name My-Name as "Donald".
r-prprc2.p
DEFINE VARIABLE wvar AS INTEGER.
DEFINE VARIABLE xvar AS INTEGER.
DEFINE VARIABLE yvar AS INTEGER.
DEFINE VARIABLE zvar AS INTEGER.
wvar = {&SEQUENCE}.
xvar = {&SEQUENCE}.
&GLOBAL-DEFINE Last-Value {&SEQUENCE}
yvar = {&Last-Value}.
zvar = {&Last-Value}.
MESSAGE "wvar =" wvar SKIP "xvar =" xvar SKIP
"yvar =" yvar SKIP "zvar =" zvar VIEW-AS ALERT-BOX.
r-prprc3.p
&SCOPED-DEFINE My-Name "Daniel"
{r-prprc3.i &My-Name = "David"}
MESSAGE "My-Name preprocessed in r-prprc3.p is" {&My-Name} + "."
VIEW-AS ALERT-BOX.
r-prprc3.i
MESSAGE "My-Name argument in r-prprc3.i is" "{&My-Name}" + "."
VIEW-AS ALERT-BOX.
&SCOPED-DEFINE My-Name "Donald"
MESSAGE "My-Name preprocessed in r-prprc3.i is" {&My-Name} + "."
VIEW-AS ALERT-BOX
During execution, the first message included by r-prprc3.i displays the value of the My-Name argument, "David". The second message included by r-prprc3.i displays the value of the following My-Name preprocessor name, defined as "Donald", permanently overriding "David"
passed by the My-Name argument. Finally, the message in r-prprc3.p displays the value of the My-Name preprocessor name that was initially defined there, "Daniel", because the value from My-Name established in r-prprc3.i ("Donald") went out of scope during compilation.
Note also that the reference to the My-Name compile-time argument in r-prprc3.i is inside double-quotes, because Progress passes string constant values for compile-time arguments without the surrounding double-quotes.
You can encounter compilation problems mixing preprocessor names with compile-time argument names. The following example, a variation of r-prprc3.i, does not compile, even when passed a My-Name argument as an include file. This is because the preprocessor My-Name value overrides the argument My-Name value.
Because the preprocessor My-Name defines a quoted "Donald" value, Progress replaces
"{&My-Name}" in the fourth line with ""Donald"". This appears to the compiler as two empty strings and an unknown variable reference (Donald). Although you can do it with care, in general, avoid using the same names for compile-time arguments and preprocessor names.
NOTES
• Progress expands preprocessor names wherever and in whatever context it finds them, including inside quoted character strings.
• If you define a preprocessor name in the same file and with the same name as a compile-time argument passed to the file, the value of the preprocessor name takes precedence over the value of the argument name from the point where the preprocessor name is defined.
SEE ALSO
&GLOBAL-DEFINE Preprocessor Directive, &SCOPED-DEFINE Preprocessor Directive,
; Special Character, { } Argument Reference, { } Include File Reference
&SCOPED-DEFINE My-Name "Donald"
MESSAGE "My-Name preprocessed in r-prprc3.i is" {&My-Name} + "."
VIEW-AS ALERT-BOX.
MESSAGE "My-Name argument in r-prprc3.i is" "{&My-Name}" + "."
VIEW-AS ALERT-BOX.
&GLOBAL-DEFINE Preprocessor Directive
Globally defines a compile-time constant (preprocessor name).
SYNTAX
preprocessor-name
The preprocessor name (compile-time constant) that you supply. Progress reserved keywords are allowed, but cannot be used in preprocessor expressions.
definition
A string of characters (or preprocessor references that evaluate to a string of characters) whose content the preprocessor substitutes for preprocessor-name during compilation. If the definition is longer than one line, a tilde (~) at the end of the first line indicates continuation to the next line.
EXAMPLES
In this example, the preprocessor name MAX-EXPENSE is defined as the text string “5000".
Wherever the reference {&MAX-EXPENSE} appears in the source code, the preprocessor substitutes the text string “5000". For example, the preprocessor changes this line of code:
to this line:
Interfaces OS SpeedScript
All All Yes
&GLOBAL-DEFINE preprocessor-name definition
&GLOBAL-DEFINE MAX-EXPENSE 5000
IF tot-amount <= {&MAX-EXPENSE} THEN DO:
IF tot-amount <= 5000 THEN DO:
NOTES
• You must place the &GLOBAL-DEFINE directive at the beginning of a line, preceded only by blanks, tab characters, or comments (/* comment */).
• The syntax of the &GLOBAL-DEFINE and &SCOPED-DEFINE directives are identical but these directives are used differently. For more information, see the chapter on the preprocessor in the Progress Programming Handbook.
SEE ALSO
{ } Preprocessor Name Reference, &SCOPED-DEFINE Preprocessor Directive, &UNDEFINE Preprocessor Directive, DEFINED Preprocessor Function
&IF, &THEN, &ELSEIF, &ELSE, and &ENDIF Preprocessor Directives
These directives set logical conditions for the inclusion of blocks of code to compile.
SYNTAX
expression
An expression that can contain preprocessor name references, the operators listed in Table 6, the Progress functions listed in Table 7, and the DEFINED preprocessor function.
When it encounters an &IF directive, the preprocessor evaluates the expression that immediately follows. This expression can continue for more than one line; the &THEN directive indicates the end of the expression. If the expression evaluates to TRUE, then the block of code between it and the next &ELSEIF, &ELSE, or &ENDIF is compiled. If the expression evaluates to FALSE, the block of code is not compiled and the preprocessor proceeds to the next
&ELSEIF, &ELSE, or &ENDIF directive. No include files referenced in this block of code are included in the final source. You can nest &IF directives.
The expression that follows the &ELSEIF directive is evaluated only if the &IF expression tests false. If the &ELSEIF expression tests TRUE, the block of code between it and the next
&ELSEIF, &ELSE, or &ENDIF directive is compiled. If the &ELSEIF expression tests FALSE, the preprocessor proceeds to the next &ELSEIF, &ELSE, or &ENDIF directive.
The block of code between the &ELSE and &ENDIF directives is compiled only if the &IF expression and the &ELSEIF expressions all test false. If there are no &ELSEIF directives, the block of code is compiled if the &IF expression tests false.
Interfaces OS SpeedScript
All All Yes
&IF expression &THEN block
[
&ELSEIF expression &THEN block] ...
[
ELSE block]
&ENDIF
Once any &IF or &ELSEIF expression evaluates to TRUE, no other block of code within the
&IF...&ENDIF block is compiled.
The &ENDIF directive indicates the end of the conditional tests and the end of the final block of code to compile.
Table 5 shows how preprocessor expressions are evaluated.
Table 5: Preprocessor Expressions
Type of Expression TRUE FALSE
LOGICAL TRUE FALSE
CHARACTER non-empty empty
INTEGER non-zero 0
DECIMAL not supported not supported
Table 6 lists the operators supported within preprocessor expressions. These operators have the same precedence as the regular Progress 4GL operators.
Table 6: Preprocessor Operators
Operator Description
+ Addition
- Subtraction
* Multiplication
/ Division
= Equality
<> Inequality
> Greater than
< Less than
=> Greater than or equal to
<= Less than or equal to
AND Logical and
OR Logical or
NOT Logical not
BEGINS Compares the beginning letters of two expressions
MATCHES Compares two strings
Table 7 lists the Progress 4GL functions supported within preprocessor expressions.
NOTE
When the preprocessor evaluates expressions, all arithmetic operations are performed with 32-bit integers. Preprocessor name references used in arithmetic operations must evaluate to integers.
SEE ALSO
&GLOBAL-DEFINE Preprocessor Directive, &SCOPED-DEFINE Preprocessor Directive,
&UNDEFINE Preprocessor Directive
Table 7: Functions Allowed in Preprocessor Expressions
ABS LEFT-TRIM R-INDEX
ASC LENGTH RANDOM
DATE LIBRARY REPLACE
DAY LOG RIGHT-TRIM
DECIMAL LOOKUP ROUND
ENCODE MATCHES SQRT
ENTRY MAXIMUM STRING
ETIME MEMBER SUBSTITUTE
EXP MINIMUM SUBSTRING
FILL MODULO TIME
INDEX MONTH TODAY
INTEGER NUM-ENTRIES TRIM
KEYWORD OPSYS TRUNCATE
KEYWORDALL PROPATH WEEKDAY
LC PROVERSION YEAR