SET Command

Description:

This command allows a value to be assigned to an integer or character variable. The values may be any integer or character values or a function reference, but their data types must match that of the variable. The values may be derived as a result of arithmetical operations.

If the variable is an integer variable, the assignment expression may be another integer variable or a numeric literal, or a complex arithmetic expression consisting of two or more integer values or variables, each separated by an operator. The following operators are supported:

+	for addition
-	for subtraction
*	for multiplication
/	for division
%	for modulo
&	bitwise AND
|	bitwise inclusive OR
^	bitwise exclusive OR

The value resulting from a division operation will be an integer, i.e. the remainder will be ignored. The modulo calculation is the converse of this operation, i.e. the variable will be set to the value of the remainder. For example:

 SET A = B / C
 SET D = B % C

If B = 13 and C = 2, then A will be set to 6 and D to 1.

Parentheses may be specified to determine the order of precedence. If parentheses are not specified, then the expression is evaluated from left to right with no other order of precedence applied.

Care should be taken when using arithmetic expressions, since there is no check for integer overflow at run-time. If an integer overflow occurs a script error will be reported.

If the variable is a character variable, the assignment expression may consist of one or more character variables or literals. Operands are separated by the addition operator if the operands are to be added together; if the second operand is to be subtracted from the first, they are separated by the subtraction operator.

The character function ~EXTRACT may be referenced within a SET command to extract a substring from a character variable or quoted character string into a character variable.

The integer function ~LOCATE may be referenced within a SET command to load the offset of a substring within a character variable or quoted character string into an integer variable.

The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error. An error could occur if, for example, an ~EXTRACT function is specified with an invalid offset, or an attempt is made to divide by zero.

Format:

 SET variable = operand1 { operator operand &
  {operator operand...} } {ON ERROR GOTO err_label}

Parameters:

variable

The name of an integer or character variable into which the result of the operation is to be placed.

operand1

The value from which the initial operation result will be taken. For a character SET command, the operand may be a character variable, quoted character string or character function reference. For integer SET commands, the operand may be an integer function reference, literal or variable.

operator

The operation which is to be performed upon the previous and following operands. For character SET commands, it may be "+" to add the first operand to the second, or "-" to subtract the second operand from the first. For integer SET commands, all operators are valid.

operand

The variable or value which is used to modify the current value for "variable". For a character SET command, the operand may be a character variable, quoted character string or character function reference. For integer SET commands, the operand may be an integer literal or variable.

err_label

A label defined within the current scope of the script, to which control branches if an error occurs.

Examples:

 SET STRING1 = STRING2 - "ERROR"
 SET STRING1 = STRING2 + STRING3 + STRING4
 SET STRING1 = STRING2 - '"END MARKER"' &
             ON ERROR GOTO Error_report

See also:

Input Stream Entry Commands