Expression replacement plays an important part in calling commands. It allows you to generate commands dynamically and modify the contents of procedure lines.
(For more information on expressions, see chapter “Expressions”.)
Expression replacement is carried out in such a way that the final inputs, or partial inputs, do not have to be specified, but only placeholders for them, which are then replaced by actual values at execution time.
Escape character
An escape character is the character that initiates expression replacement. This character immediately precedes the expression which is to be replaced and indicates that the subsequent characters do not represent the actual operand value, but only a placeholder.
A distinction must be made between two uses of the escape character:
commands and statements
data lines.
For commands and statements, the escape character is &.
The character that is to serve as an escape character in data lines can be determined in the procedure head using the SET-PROCEDURE-OPTIONS command (DATA-ESCAPE-CHAR operand). The characters &, #, *, @ and $ are available for selection.
Unless otherwise specified, expression replacement does not occur in data lines;DATA-ESCAPE-CHAR = *NONE applies.
Because the character & is the default escape character, expression replacement is also referred to below as & replacement.
It should be noted that if an expression or a variable is preceded by an escape character, the value of this expression or variable will not be processed directly by the command, but instead as though its value had been written in place of the escape character string in the input record. (Direct expression replacement, for example /SET-VARIABLE A=B, will only be performed by a command if the command supports an expression, otherwise escape character strings must by used)
The rules described in the sections below apply to expression replacement in commands and statements and in data lines.
Example
/SHOW-FILE-ATTRIBUTES &FILE
This displays the file attributes of a file whose name is stored in the FILE variable.
Syntax
In structured procedures, the escape character can be applied not only to variables (including procedure parameters), but also to functions, expressions and job variables. The following syntax applies for expression replacement:
&(expression) |
or
&name |
Where:
| & | Escape character |
| expression | An expression or the name of a job variable |
| name | The name of a variable (if it contains no period) or the name of a predefined function without parameters |
Rules
“expression” is evaluated, and the result value is converted to the STRING data type and then used as the current operand value.
If “expression” is a function call with the format &(function( )), this function is executed and the result of the function is used as the current parameter value. The function call can contain input parameters.
If “expression” is a name, a variable with the corresponding variable name is first searched for. As with non-S procedures, an entry &(name) is evaluated as follows:
A variable with this name is searched for.
If no such variable exists, a function with this name is searched for.
If neither a variable nor a function with the specified name exists, then a search for a corresponding job variable will either be made or not, depending on the setting of the JV-REPLACEMENT operand in the SET-PROCEDURE-OPTIONS or MODIFY-PROCEDURE-OPTIONS command. If the value here is set to *AFTER-BUILTIN-FUNCTION, a job variable will be sought; if the setting is *NONE, no search is made.
If the specified name does not designate a variable, function or job variable, error handling is activated.
The first character to follow the escape character can be:
an open parenthesis (as separator (entry: &(expression))
the first character of a variable or function name (entry: &name)
To ensure that & characters in text are retained, instead of acting as escape characters, single escape characters should be replaced by double ones (&&).
If “name” is followed by a period “.”, this period is lost in expression replacement (compatible with non-S procedures).
If “name” is followed by special characters, these characters are interpreted as separators. In contrast to non-S procedures, hyphens in the name are also translated and do not function as separators. (Example: &JOB-CLASS is replaced by the current job class, e.g. JCB00200.)
Commands or data lines may contain any number of expression replacements.
Expression replacements can be nested; however, recursive expression replacement is not possible. If, for example, &(expression) is replaced by the characters A + &B, &B is not evaluated further; the character & next to the B is retained.
Expression replacement cannot be executed before a tag or in a tag.
If an error occurs during expression replacement, error handling is activated, unless otherwise specified. Error handling can be suppressed for data lines by means of the operand DATA-ERROR-HANDLING = *NO in the SET-PROCEDURE-OPTIONS command.
Error handling will also be activated if a procedure line contains an & character by itself.
Restrictions
Expression replacement cannot be used to generate control flow commands. If a control flow command does contain an expression replacement in the command name, it is rejected at the time of procedure execution.
The following characters and names cannot be generated by expression replacement:
continuation characters at the end of a procedure line
an escape character that is then to function recursively
the separator for commands or statements (semicolon “;”)
branch tags or block names
commands which cannot be generated by expression replacement:
SDF-P control flow commands:
BEGIN-BLOCK BEGIN-PARAMETER-DECLARATION CYCLE DECLARE-PARAMETER ELSE, ELSE-IF END-BLOCK, END-FOR, END-IF, END-WHILE END-PARAMETER-DECLARATION EXIT-BLOCK FOR GOTO IF, IF-BLOCK-ERROR, IF-CMD-ERROR INCLUDE-BLOCK REPEAT UNTIL WHILE
AID commands that are followed by a command list or subcommand list (see the “AID” manual [6])
SDF command SET-JOB-STEP (see “Commands” [3])
OPEN-VARIABLE-CONTAINER in the DECLARE-VARIABLE block before the first DECLARE-PARAMETER command.
In some commands expecting a branch tag or a block name as input for a specific operand, expression replacement is completely suppressed for all operands. Affected commands:
GOTO,
INCLUDE-BLOCK,
EXIT-BLOCK,
CYCLE