Section 3.3

3.3 CONSTANTS, VARIABLES, ASSIGNMENTS, EXPRESSIONS, AND FUNCTIONS

3.3.1 Constants

A constant in TCL must be an integer, a real, or a string. It may be single-valued or multi-valued. If multi-valued, the values must appear in parentheses, separated by commas or spaces.

The "null value" constant consists of two adjacent "-" characters. The null value is a value with an element count of zero. Example:

TAE> LOCAL I INTEGER COUNT=0:1

TAE> LET I = --

For the above statement to be valid, the variable "I" must be declared to be "nullable," i.e., allowing a zero count.

3.3.1.1 Integer and Real Constants

The rules for acceptable integer and real constants are described in the "TAE Command Language (TCL) User's Manual."

3.3.1.2 String Constants

A string constant consists of any characters acceptable in the host system's character set.

The rules for quoting string constants are as follows:

String constants, except those used as parameter values in a TCL command or proc invocation, must be surrounded by quotation marks.

String constants in parameter values need not be quoted unless the string contains special characters or blanks.

VAX/VMS and UNIX file specifications do not have to be quoted in proc invocation commands.

Examples:

MAIL Harry Jane F=file1     !see rule 2
LET X = "file1"             !see rule 1
IMGCOPY filel libe/file2    !see rule 3
PUTMSG "Send this to Harry" !see rule 2

3.3.1.3 Empty Strings

In TCL, two consecutive quotation marks indicates an empty string, that is, a string with zero length.

If a parameter value in a proc invocation is omitted, the default value is assumed; if an element in a value list is omitted, the value assumed is zero for a numeric, or the empty string for a STRING type variables.

The value field (i.e., the right hand side) of a FOR or LET command may not be omitted.

Examples:

LET X =""               !Set X to empty string
LET X =                 !Error
PROC x=1, y=(1,,100)    !Use zero for y(2)
PROC X=, Y=2            !Use default for X

3.3.2 TCL Variables

A TCL variable is an object that may be assigned a value using the LET command (e.g., LET x = 2). Variables may be used interactively as well as in procedures.

The following attributes are associated with variables:

a "type", describing the allowable values the variable may assume;

a "scope"--global or local--indicating whether or not the variable can be accessed outside the local procedure;

a minimum and maximum "count", specifying the minimum and maximum number of elements that may appear in a multi-valued variable;

a "nullability" attribute, specifying whether the variable accepts the null value;

a valid check, further limiting the acceptable values that the variable may assume.

Local variables are declared using the LOCAL command; global variables are declared using the PARM command in a GLOBALS PDF. Parameters and parameter qualifiers are declared using the PARM command.

3.3.2.1 Variable Reference Syntax

In general, a variable is referenced by specifying the name of the variable or the name of a variable followed by a subscript.

A parameter qualifier is a variable associated with another variable. Parameter qualifiers are referenced by specifying the parameter name, followed with a ".", followed by the qualifier name with no spaces in between. All rules which apply to variables will also apply to the parameter qualifiers, except as specified.

The nth element of variable X is referenced by "X(n)". This syntax is valid anywhere a variable reference is permitted, except:

When variable substitution is requested (i.e., substitution using "&").

When a variable is de-referenced using the "@" character.

When a variable is the value of a NAME parameter in a proc invocation.

On the left side of a FOR command.

A subscript may be any valid TCL integer expression.

If variable X is a parameter qualifier to variable V, the nth element of variable X is referenced by "V.X(n)".

3.3.2.2 Variable Types

The variable types in TCL are INTEGER, REAL, STRING, KEYWORD, NAME, and FILE. Types are associated with a variable explicitly, through a LOCAL or PARM command.

The rules for acceptable values for each type are:

Values of variables of type INTEGER must be integer constants, or real constants with no significant fraction (e.g., 3 or 1.0E4).

Values of variables of type REAL must be integer or real constants.

Values of type STRING must be string constants.

Values of type FILE must be string constants.

The value of a NAME parameter is the name of another variable. (Only parameter variables may be of type NAME).

Values of type KEYWORD must be one of the acceptable keys defined for the parameter. (Only parameter variables may be of type KEYWORD).

3.3.2.3 Multi-valued Variables

A multi-valued variable is a variable that is declared to have a maximum count greater than one. References to multi-valued variables are acceptable in the following places:

in proc invocations

on the left side of an assignment

as values for parameters with a TYPE of NAME

standing alone on the right side of an assignment

An unsubscripted multi-valued variable is not permitted in an arithmetic or string expression.

A variable may be declared to have a variable number of elements (using the COUNT attribute). If a variable is declared to have a variable number of elements, then the actual count is set to the count implied by the last assignment. The actual count is available through the $COUNT built-in function.

Example:

LOCAL x COUNT=1:4 INITIAL=1   !Actual count=1
    . . .
LET x = (1,4,32)              !Actual count=3
LET x = 2                     !Actual count=1

When referencing individual elements of a multi-valued variable, the index value must not be greater than the actual count.

3.3.2.4 Nullable Variables

A nullable variable is allowed to assume the null value. The null value is indicated by "--" and may be regarded as a vector with a count of zero and (consequently) no components.

Arithmetic may not be performed with null values. (Arithmetic is only valid for variables with a count of one.)

A parameter declared to be nullable has the nice property that a "special value" exists (i.e., the null value) without usurping the space of substantial values. Applications often use the null state of a nullable parameter as a flag to indicate "do nothing".

An example of using the null value as a special flag is the hypothetical IMGCOPY proc:

PROCESS
PARM INPUT   TYPE=FILE
PARM OUTPUT  TYPE=FILE
PARM RECORDS TYPE=INTEGER COUNT=O:1 +
     DEFAULT=--    !null by default
END-PROC

This proc, by default, copies the entire INPUT file to the OUTPUT file. If, however, the user sets RECORDS to a substantial value, the specified number of records is copied.

Note that "null value" is different from "no value." When a proc invocation request is processed by TAE, the request is rejected if one of the parameters has no value. If a parameter has no DEFAULT specification, a value must be supplied in the invocation request. A nullable parameter, like any other parameter, must have a value upon proc invocation; the value for a nullable parameter may be a substantial value or the null value.

3.3.2.5 Variable Scope

A variable's scope may be local or global.

3.3.2.5.1 Local Variables

A local variable is declared using the LOCAL command. A local variable may be referenced only within the PDF in which it is declared.

Local variables may be qualified, using the same syntax and rules as for qualification of parameters. (See Section 2.3.4.) In the following example, the local variable SAT is qualified by the parameters in the internal proc, SATQUALS:

procedure
    parmset name=SATQUALS
    parm satid ! Satellite ID
    parm type ! Satellite type
    end-proc
local sat init=LANDSAT quals=SATQUALS

body
let sat.satid= "LST-D"
let sat.type = "POLAR"
someproc @sat|@sat.satid, @sat.type|
end-proc

Note: The LET statement copies only the highest level value; it does not copy the qualifiers. For example, if A and B are variables with the same qualifier Q, "LET A = B"sets A to the value of B, but does not set Q.

Note that a local variable contained in a PAR file may be restored into a parameter that has the same name as the local. This is true for the TCL RESTORE command qualifier and also for TUTOR's RESTORE command.

3.3.2.5.2 Global Variables

A global variable may be accessed from any execution level. The rules for global variables are:

A global (or, more typically, a collection of global variables) is defined by a PARM command in a special "global definition" PDF. A global definition PDF begins with the GLOBALS command rather than the PROCESS, PROCEDURE, or PARMSET command.

Any proc that references a global must include a REFGBL command naming the global. (Some implicit globals are referenced in every PDF; see below.) As a convenience to the interactive user, all globals are implicitly referenced on the interactive level. Global references in a proc do not participate in a tutor session for the proc.

The value of a global may be changed subsequent to its initial definition using one of the following methods:

Assignment with the LET command, either interactively or in a procedure.

Alteration by a process. A process may call the XQOUT subroutine in the FORTRAN program, or the q_out or the Vm_SetTCLVar subroutine in the C program to change the values of globals that are referenced in the PDF. See the q package (Section 3.9 in the "TAE Command Language (TCL) Runtime Services, Volume 1: C") the Vm_package (in "TAE Plus Programmer's Manual" and "TAE Plus C Reference Manual"), the tae_vm package (Appendix C of the "TAE Plus Ada Reference Manual"), or the TaeVar class in the "TAE Plus C++ Programmer's Manual".

Alteration by a proc through reference as a NAME parameter in a proc invocation.

Tutoring on the global PDF.

Globals are deleted using the DELETE-GLOBALS command (a command described in the "TAE Command Language (TCL) User's Manual.") Globals are automatically deleted when the LOGOFF or EXIT commands are executed.

The current value of a global may be displayed using the DISPLAY command.

Global variables may be used as DEFAULT values in PARM commands. This gives the user the capability to make a "local" change (i.e., for the duration of one proc) to a global value.

The values of global variables may be saved to disk with the SAVE-GLOBALS command. The values may be subsequently restored with the RESTORE-GLOBALS command.

Global variables may be qualified, using the same syntax and rules as for qualification of parameters. (See Section 2.3.4.)

Examples:

GLOBALS
PARM WINDOW TYPE=INTEGER COUNT=4 +
    DEFAULT=(0,511,0,511)     
PARM BANDS TYPE=INTEGER COUNT=1:6 +
    VALID=1:6 +         
    DEFAULT=(1, 2, 3, 4, 5, 6)
END-PROC

    DEFPAR WINDOW (0 767 0 767)

TAE>LET WINDOW=(0, 511, 0, 511)

PROCEDURE
REFGBL WINDOW
    .
    .
    .
LET WINDOW = (0, 767, 0, 767)
    .
    .
    .

PROCESS
REFGBL WINDOW
END-PROC

PROCESS
REFGBL WINDOW
PARM _WINDOW TYPE=INTEGER COUNT=4 + 
    DEFAULT=&WINDOW
END-PROC

Section 3.3.2.8

TAE>DELETE-GLOBAL DEFPAR

3.3.2.5.3 Variables Defined in Internal Procs

An internal proc may access variables declared within itself or in an outer proc. The variable is first searched for in the internal proc, and if it is not found, the search moves to the outer proc. The search continues on through the layers of outer procs ending with the outermost, containing proc. However, the internal proc may only delete variables declared within itself.

An outer proc may not access the variables declared in its internal procs.

3.3.2.6 The Relationship Between Variables and Proc Parameters

A parameter has the status of a local variable within the procedure where the parameter is declared. The following rules therefore apply:

The parameter may be assigned a value in a procedure as any other variable is assigned a value; if the parameter's type is not NAME, the effect is to assign a value to the local variable.

If the type is NAME, the effect of assignment is to set the value in the referenced variable.

If the type of the parameter is not NAME, the initial value of the variable is the passed value of the parameter; if no value is passed and a DEFAULT has been specified in the PARM command, then the initial value is the default.

If the type of the parameter is NAME, the initial value is the value of the corresponding variable in the calling procedure; if there is no value for the corresponding variable, then the initial value is undefined.

The count of an undefined TCL value is -1; thus, a procedure may use the $COUNT function to determine whether the reference of a NAME parameter has a value.

3.3.2.7 Implicit Variables

Implicit variables are local or global variables that have been declared within TCL.

3.3.2.7.1 Implicit Global Variables

By convention, the names of implicit global variables start with "$". The globals and the corresponding implicit definitions are as follows.

$AECHO:	TYPE=STRING COUNT=1:1O DEFAULT=NO VALID=(YES,NO,FULL,BODY,TRACE) $AECHO is the echo global for asynchronous jobs. The values for $AECHO are the same as $ECHO, except that level 0 is always echoed. $AECHO may be set using the LET command.
$APLIB:	TYPE=STRING COUNT=0:15 DEFAULT="" $APLIB contains the names of the currently active application libraries. At the beginning of a session, SAPLIB consists of the null value, indicating that there are no application libraries defined for the hierarchy search.
$BECHO:	TYPE=STRING COUNT=1:10 DEFAULT=NO VALID=(YES,NO,FULL,BODY,TRACE) $BECHO is the echo global for batch jobs. The values for $BECHO are the same as $ECHO, except that level 0 is always echoed. $BECHO may be set using the LET command.
$DEFCMDO:	TYPE=STRING DEFAULT=-- COUNT=1:50 $DEFCMDO is a multi-valued string containing the string equivalents for commands defined by the DEFCMD command. Each value is of the form "command=translation" where "command" is the command the user enters and "translation" is the character string substituted for the command. An example of a value in $DEFCMDO would be MSGHELP=HELP-MESSAGE where "" indicates that the left-hand characters may be used as an abbreviation. If more than 50 commands are defined, TAE creates another global named SDEFCMD1, continuing up to $DEFCMD9 if necessary.
$DYNTUT:	TYPE=STRING VALID=(SCREEN,NOSCREEN) DEFAULT=NOSCREEN $DYNTUT controls the tutor screen formatting for dynamic tutor. If "NOSCREEN", then "NOSCREEN" tutor mode is used. If "SCREEN", then normal screen-oriented'' tutor mode is used. $DYNTUT may be set using the LET command.
$ECHO:	TYPE=STRING COUNT=1:10 DEFAULT=NO VALID=(YES,NO,FULL,BODY,TRACE) $ECHO is the echo global for synchronous jobs. The ith element of SECHO applies to the ith level of proc with level 0 never echoed. In addition, the last element set for SECHO applies to all subsequent levels. If "BODY" or "YES", the body portion of the procedure will be displayed as the commands are executed; if "FULL", the declarations plus the body will be echoed; if "TRACE", the full file specification of the PDF will be echoed upon proc invocation; and if "NO", no echo at the level. $ECHO may be set using the LET command.
$FILEVER:	TYPE=STRING COUNT=1:2 DEFAULT=NO VALID=(YES,NO) $FILEVER defines whether or not TAE checks for the existence of a file when a parameter is of type FILE and ACCESS is IN or INOUT. If $FILEVER is "YES" then file existence is checked; file existence is not checked if $FILEVER is "NO". The default for $FILEVER is "NO".
$JOB:	TYPE=STRING $JOB is automatically initialized to the name of the current job. For interactive jobs, SJOB is equal to $SESSION; for ASYNC jobs, $JOB is the name assigned by the parent job.
$LASTCMD:	TYPE=STRING DEFAULT="" COUNT=0:20 $LASTCMD contains the 20 most recent interactive command strings typed by the user. $LASTCMD(1) is the most recent command, $LASTCMD(2) is the command previous to SLASTCMD(1), and so on. Thus, a user may examine old commands with "DISPLAY $LASTCMD". If SLASTCMD is set to the null value ("LET $LASTCMD = =--"), the archiving of previous commands into $LASTCMD is disabled, and the user may not recall commands using the arrow keys.
$LOG:	TYPE=(STRING,file-spec-size) DEFAULT="session.tsl" In a future release of TAE, $LOG will contain the file specification of the current session log. $LOG is automatically initialized by TAE when the first ENABLE-LOG command is executed.
$MENUOPT:	TYPE=STRING COUNT=0:4 VALID=(NO_PRESS_FOR_MENU, NO_TAG,NO_NAME,NO_LIBRARY) DEFAULT=-- $MENUOPT allows suppression of the "Press RETURN key for menu" message and controls the display of menu header information. If $MENUOPT has the value NO_PRESS_FOR_MENU, then the Terminal Monitor suppresses the "Press RETURN key for menu" message that usually appears before a menu is reprinted. If $MENUOPT has the null value (--), the default, then the "Press RETURN key for menu" message is displayed. "NO_TAG" suppresses the "Menu:" part of the menu screen header; "NO_NAME", the proc name; and "NO_LIBRARY", the library name. Note also that to set more than one of these attributes, include the attributes in a list. For example, LET $MENUOPT=("NO_PRESS_FOR_MENU", "NO_TAG"). The value of $MENUOPT, like all string global variables, may be changed from a program using the XQSTR and XQOUT subroutines (FORTRAN), the q_string and q_out subroutines (C), or the Vm_SetString and Vm_SetTCLVar subroutines (C).
$MENUS:	TYPE=STRING COUNT=0:50 $MENUS is the stack of active menu definition file names. $MENUS(1) is the root menu, $MENUS(2) is the menu activated under the root, and so on. The current menu is $MENUS(n), where "n" is $COUNT($MENUS). An executing proc may alter $MENUS in order to set the menu that the user sees upon proc termination.
$MESSAGE:	TYPE=STRING VALID=(ATTN,SILENT,PAUSE,BELL) DEFAULT=SILENT $MESSAGE controls the terminal action when a message is displayed. With "BELL", TAE sounds the terminal bell and continues; with "PAUSE", the user must press the RETURN key to continue execution; "ATTN" is the combination of "BELL" and "PAUSE"; and "SILENT" means there is no special action for messages. $MESSAGE may be set by the user with the LET command.
$PARENT:	TYPE=STRING For ASYNC jobs, $PARENT is the name of the parent job, i.e., the job that initiated the ASYNC job. For interactive jobs, $PARENT is the null value.
$PROMPT:	TYPE=(STRING,15) DEFAULT="TAE" The value of $PROMPT is used as the standard TCL prompt.
$RUNTYPE:	TYPE=(STRING,12) DEFAULT="INTERACTIVE" $RUNTYPE contains "BATCH", "ASYNC" or "INTERACTIVE" and is automatically set by TAE. $RUNTYPE is implicitly referenced by every PDF. "INTERACTIVE" is the initial value for an interactive session.
$SESSION:	TYPE=STRING $SESSION is a string which uniquely identifies the current batch, asynchronous or interactive session. $SESSION is implicitly referenced by every PDF.
$SFI:	TYPE=INTEGER DEFAULT=1 The value of $SFI ("success/fail indicator") upon the termination of a proc determines the TCL error handling. A positive value indicates success and a negative value indicates failure. When a proc is invoked, $SFI is automatically set to 1 before the execution of a proc. (See Section 3.5.) $SFI is implicitly referenced by every PDF.
$SKEY:	TYPE=(STRING,17) DEFAULT="" $SKEY is a proc termination status key and is used as a method of passing completion information to the invoking proc. When a proc is invoked, $SKEY is automatically set to the empty string before execution of the proc. $SKEY is implicitly referenced by every PDF.
$SWITCH:	TYPE=INTEGER DEFAULT=0 $SWITCH is the TAE "switch word." The switch word is used by programmers to pass special mode flags to procs. The low-order eight bits of the switch word are reserved for use by the TAE developers. Two $SWITCH values are of special interest. 1, enables debug mode for application processes. 32 (20 Hex), disables all validation of a parameter's value. TAE Plus uses this to disable validation during .rfg file to .res file translation. $SWITCH is implicitly referenced by every PDF.
$SYSCHAR:	TYPE=STRING COUNT=0:6 $SYSCHAR contains information on system characteristics. The keyword strings in this variable are referenced by help files to generate "conditional" help text. Thus, one help file may be used on several different implementations of TAE and, where needed, generate system-specific information.
$SYSLIB:	TYPE=(STRING, file-spec-size) COUNT=0:1 DEFAULT=SYSLIB $SYSLIB contains the name of the system library. At the beginning of a session, $SYSLIB is automatically set to the name of the installation's standard TAE system library. $SYSLIB may be altered during a session in order to change the proc hierarchy search. If $SYSLIB is set to the null string, the hierarchy search bypasses the system library.
$TUTOR:	TYPE=STRING DEFAULT=SCREEN VALID=(SCREEN,NOSCREEN) $TUTOR controls the tutor screen formatting. If it is set to "NOSCREEN", then "NOSCREEN" tutor mode is used. If it is set to "SCREEN", then normal "screen-oriented" tutor mode is used. $TUTOR may be set using the LET command.
$TUTOPT:	TYPE=STRING COUNT=O:3 DEFAULT=-- VALID=(NO_TAG,NO_NAME, NO_LIBRARY, COMPRESS, NO_SELFTUTOR) $TUTOPT is for tailoring the tutor screen. "NO TAG" suppresses the "Tutor:", "NO NAME", the proc name, and "NO_LIBRARY", the library name on the screen. Setting $TUTOPT to "COMPRESS" requests compressed tutor for all subsequent tutor sessions. All PDFs are treated as if OPTIONS=COMPRESSTUTOR were specified. Setting $TUTOPT to "NO_SELFTUTOR" causes TAE to ignore the OPTIONS=SELFTUTOR in any subsequently invoked proc. This feature exists primarily for testing procs before the proc's self-tutoring logic is working. To set more than one of these qualifiers, include them in a list. For example, LET $TUTOPT=("NO_NAME", "NO_TAG") Note that the $TUTOPT is a nullable vector, so to remove the all of the current settings, set the variable to the null value. LET $TUTOPT = --
$USERLIB:	TYPE=(STRING,file-spec-size) COUNT=O:1 DEFAULT=<see below> $USERLIB contains the name of the user library. At the beginning of a session, $USERLIB is automatically set to the library defined by the system manager for the current user. SUSERLIB may be altered during a session in order to change the proc hierarchy search. If $USERLIB is set to the null string, the hierarchy search bypasses the user library.

3.3.2.7.2 Implicit Local Variables

By convention, the names of implicit local variables start with the underscore character ("_"). The following local variables are implicitly defined in every proc:

_ONFAIL	TYPE=(STRING, 80) COUNT=1:2 INITIAL="RETURN" _ONFAIL(1) contains the command string to be executed when $SFI is less than zero following execution of a proc. _ONFAIL(2) contains the command string to be executed when the procedure is aborted via the ABORT command from proc interrupt mode. The use of _ONFAIL for exception handling is described in Section 3.5.1.
_PROC	TYPE=STRING _PROC contains the name of the proc invoked.
_SUBCMD	TYPE=STRING _SUBCMD contains the name of the active subcommand (fully-spelled and in the same case as the proc's SUBCMD definition). If the subcommand was defaulted on the proc activation command, then the proc's default subcommand is contained in _SUBCMD.
_STDOUT	TYPE=(STRING, file-spec-size), COUNT=2, INIT=TERMINAL The first element of _STDOUT contains the standard output file name. The second element contains either "APPEND", meaning the current standard output is to be extended, or "CREATE", meaning a new file is to be created. (See Section 2.2.2 for a discussion of standard output.) Note that _STDOUT is set automatically when the STDOUT command qualifier is used. If _STDOUT is set using LET, the results are unpredictable.
_TUTOR	TYPE=INTEGER When TAE receives an initial tutor request for a proc declared as SELFTUTOR, _TUTOR is set to one, otherwise it is set to zero.

3.3.2.8 Variable Substitution

Variable substitution is the substitution in a command line for a variable by the character string that represents the value of the variable. Substitution always occurs before command interpretation and before variables in expressions are evaluated.

The rules relating to substitution are:

Substitution for a variable is indicated by an ampersand (&) immediately preceding the variable name.

Substitution may be used anywhere on the command line, including within quoted strings.

Substitution always occurs prior to the interpretation of the command string.

The string that is substituted is not enclosed in quotation marks (even if the string contains special characters).

If the referenced variable has no value, the substitution is not allowed and the command is terminated abnormally.

To include the ampersand literal within a quoted string, two ampersands must be used. See Example 4 below.

Substitution is not recursive; if an ampersand appears in a line as a result of substitution, the ampersand does not indicate further substitution.

Substitution may not be specified for a variable written with a subscript.

Substitution does not occur within comment fields.

If the substitution is for a multi-valued variable or parameter, the string substituted contains parentheses if and only if the number of actual values is greater than one.

If the command string is echoed, it is displayed with the result of the substitution.

If the referenced variable has the null value, the substitution request is successful but nothing is substituted.

If the referenced variable is a string parameter with embedded quotes, the substitution process does not "re-double" the quotes.

An alphanumeric TCL variable name must immediately follow the ampersand. The variable name may be quoted to distinguish the variable from adjacent characters. See Example 7 below.

Variables may appear in menu definition files (Section 4.1) and help files (Section 2.15.3.).

Examples:

LET I = "myfile"
IMGCOPY &I hisfile       !Copy myfile to hisfile

PARM X TYPE=STRING DEFAULT="no message"
   . . . 
WRITE "&X"           !WRITE "no message"

LET Q = "L1,L2"
SETLIB (L0, &Q, L3)   !SETLIB (L0, L1,L2, L3)

WRITE "DISPLAYS ONE && TWO WERE GENERATED"

LET F="afile" 
FOR I=1,2,3
    PRINT &F&I
END-FOR

let x="hello"
DISPLAY &X     !Will display the value
               !of the variable HELLO.

LET DIR = "[MYFILES]"
DUMP &"DIR"DATA.DAT

3.3.2.9 De-referencing

The "@" character may be used in a value field of a proc invocation command to indicate "use the value of the following variable." Use of the "@" syntax is called "de-referencing the variable" (because, without the special syntax, the variable name would be taken as a string constant).

The rules associated with de-referencing are:

De-referencing may only occur in one of the parameter value fields of a proc invocation command. The value field may be a positional field or field explicitly associated with a parameter name.

The variable being de-referenced may not be indexed.

The exact value associated with the variable is used as the value of the corresponding parameter. The variable must agree in type and count with the corresponding parameter.

The differences between substitution and de-referencing are:

Substitution may be performed anywhere in the command string. Substitution is performed before the string is interpreted as a command conforming to TCL language syntax.

In contrast, de-referencing is part of the TCL language syntax and is limited to parameter value fields.

De-referencing is preferred over substitution in parameter value fields because de-referencing produces the proper results for null values, empty strings, and strings with embedded quotes.

Example:

IMGCOPY INPUT=@FILE1 OUTPUT=@FILE2

3.3.3 Assignment

In an "assignment" operation, a FOR or LET command sets the value of a variable to the value of an expression.

Examples:

LET X = Y + 8        !Y is a variable
FOR VAR = 1,2,3,4    !4 assignments in a loop

The value that is associated with the named variable is the constant produced by the evaluation of the expression.

3.3.4 Expressions

An expression is a rule for calculating a value based on constants, variables, functions, and operators. TCL provides numeric expressions, string expressions, and logical and relational expressions.

NOTE: Expressions are not permitted in proc invocations or in TCL commands using proc invocation form. Expressions are limited to the LET, FOR, IF, and ELSE-IF statements.

3.3.4.1 Numeric Expressions

The possible forms of a numeric expression are:

unary-operator term

unary-op term operator term operator term .

A "term" may be a constant, an integer or real variable, or an integer or real function. A variable or a constant representing a term may be preceded by a unary + or - Spaces are not required between a term and an operator.

A term may not include a multi-valued variable or a variable with the null value. The general operators defined for numeric expressions are:

+ for addition

- for subtraction

* for multiplication

/ for division

The unary operators are + and -

See "Evaluation of Expressions," below, for details on the order of evaluation.

Examples of numeric expressions:

I + 1 - 1001
X + Y/Z
-6
5 * 2.2E-4 *6002
Z
(X+Y)/Z
I + $FIX(R)

3.3.4.2 String Expressions

String expressions are used for the concatenation of string constants and/or variables.

The form of a string expression is:

string // string //. . .

The "string" may be a string constant, variable, or function; "//" is the concatenation operator. "String" may not be a multi-valued variable or a variable with the null value.

Examples:

"libe"//".myfile"
X//"myfile"
"THERE WERE "// "&N" //" IMAGES PROCESSED"

3.3.4.3 Mixed-Type Expressions

An expression must not contain constants and variables with more than one type except inside relational expressions (Next Section). In addition, the constants and variables on the right-hand side must have the same type as the variable on the left. (Recall that constants of the form 1.0 and 1E3 qualify as valid integers and that 1 is a valid real.)

Functions are available for converting reals to integer and integers to reals. See Section 3.3.5.

3.3.4.4 Relational Expressions

Relational expressions provide the capability to perform comparisons between numeric expressions or between string expressions. The result of the evaluation of a relational expression is an integer value with 0 representing false and 1 representing true. The form of a relational expression is:

expression relational-operator expression

The terms in a relational expression may be numeric or string expressions (including numeric or string constants). The relational operators are:

>		greater than
>=		greater than or equal to
<		less than
<=		less than or equal to
=		equal to
<>		not equal to

Multi-valued variables may not be compared using the relational operators. Strings are limited to the "equal" and "not equal" operators; null values are also limited to the "equal" and "not equal" operators.

Real variables can be assigned the result of a relational expression. Mixed-types are allowed across relational operators.

Examples:

IF ( x < 3 ) . . .
IF ( S = "myname" ) . . .
IF ( I >= 3E2 ) . . .
IF ( x+y/2 > z*10E6 ) . . .
LET x = ( n < 3 )

3.3.4.5 Logical Expressions

A logical expression is the logical combination of relational expressions. The form of a logical expression is:

relational-expression logical-op relational-expression...

Logical operators are AND and OR; in addition, a logical expression may be preceded by the logical NOT.

If the operator is AND, the expression is "true" if the relational expressions on both sides of the AND are true, and "false" otherwise.

If the operator is OR, the expression is "true" if either adjacent relational expression is true; "false" if neither is true.

Examples:

IF ( X<3 AND S="myfile" ) . . .
IF ( 1<A AND A<10 ) . . .
IF ( S="A" OR S="B" OR S="C" ) . . .

The result of a logical expression is an integer value, where 0 represents false and 1 represents true. Logical expressions may be used on the right side of a LET statement for an integer or real variable.

3.3.4.6 Evaluation of Expressions

The meaning of "LET X = Y" is that the value associated with the variable X becomes the value that is assigned to the variable Y. If the expression on the right side is not a single variable or a constant, then the expression is evaluated as indicated by the "operator precedence" rules below.

3.3.4.6.1 Operator Precedence

Expression evaluation is left to right, subject to the operator precedence order given in Table 3-3.

TABLE 3-3

Operator Precedence Order

Operators in the following table are listed in order of precedence, where the higher precedence items are listed first, and operators on the same row have equal precedence. Parentheses may be used anywhere to alter the precedence order.

unary operators		+ - NOT
binary operators		* / + -
concatenation		//
relational operators		< > <> >= <= =
logical operators		AND OR

3.3.5 Functions

By convention, the names of functions start with a dollar sign. A function returns a value and may be treated as a variable. The following rules apply to TCL functions:

Functions are permitted wherever variables are permitted, except as the value of a NAME parameter in proc invocations or in substitution.

If a variable is declared with the same name as a function, then a reference to that name refers to the variable, i.e., the function becomes unavailable.

Any appropriate TCL expression is permitted as an argument in functions.

The form of a function reference is:

function-name (argument-list)

The argument list is a comma-separated list of values.

Example:

LET X = $FLOAT(I)

The TCL functions are described below.

3.3.5.1 $FIX(real)

$FIX converts the argument to an integer, by truncation, and returns the result.

Function type:

integer

Arguments:

REAL is a real expression.

3.3.5.2 $FLOAT(int)

$FLOAT converts the provided argument to a real and returns the result.

Function type:

real

Arguments:

INT is an integer expression.

3.3.5.3 $STRLEN(string)

$STRLEN returns the length of the specified string.

Function type:

integer

Arguments:

STRING is a string expression.

3.3.5.4 $COUNT(name)

$COUNT returns the current number of elements for the variable named. If the variable has no value, then $COUNT is -1; if the variable has the null value, then $COUNT is 0.

Function type:
integer

Arguments:
NAME is the name of a variable.

3.3.5.5 $GLOBAL(name)

$GLOBAL returns for the variable named the status of its existence as a global. If the variable is found defined as a global, then $GLOBAL is 1; otherwise, $GLOBAL is 0.

Function type:
logical

Arguments:
NAME is the name of a variable.

3.3.5.6 $ASFI(jobname)

$ASFI returns the current value of $SFI for the asynchronous job.

Function type:
integer

Arguments:
JOBNAME is the name of an asynchronous job.

Example:

IMGCOPY |RUNTYPE=ASYNC| LET JOBNAME = $SKEY . . . IF ($ASFI(JOBNAME) > 0) !Success . . .

3.3.5.7 $ASKEY(jobname)

$ASKEY returns for the asynchronous job named the current value of $SKEY.

Function Type:
string

Arguments:
JOBNAME is the name of an asynchronous job.

3.3.5.8 $PANEL(panelname)

$PANEL returns for the named panel the status of its existence. If the panel exists, $PANEL is 1; otherwise, $PANEL is 0.

Function type:
logical

Arguments:
PANELNAME is the name of a panel.