
Cantata(Variables)           Khoros            Cantata(Variables)

     VARIABLES USAGE

     The `Variables' subform contains an "interactive entry win-
     dow", labeled `Enter Expression', which is used to communi-
     cate with the cantata expression parser.  To enter an
     expression, place the mouse cursor in the window, type the
     desired expression, then hit the Return key.  The value
     returned by the parser will be displayed as the `Result of
     Evaluation' immediately below the `Enter Expression' window.

     Valid expressions may include variables, standard arithmetic
     `operators', and `logicals', as well as predefined `con-
     stants' and `functions' (see additional documentation on
     these topics).  Any string of alpha/numeric characters,
     beginning with a letter, may be used as a variable.

     To define a variable enter an equation of the following
     form:

          variable = expression

     To check the value of a defined variable, or to evaluate an
     expression, simply enter it.  The value will be displayed as
     the `Result of Evaluation'.

     Examples

     (a)  To set x equal to 10, type "x=10" in the `Enter Expres-
          sion' window, then press the carriage return key to
          enter it.  The result, "10" will be displayed as the
          `Result of Evaluation'.

     (b)  To increment x by 1, enter "x=x+1".  (It may be neces-
          sary to delete the previous entry before typing in a
          new one.) The result in this case will be "11".

     (c)  To check the value of x, enter "x".  The current value
          of x, "11", will be displayed as the `Result of Evalua-
          tion'.

     (d)  To determine the natural log of x, enter "ln(x)".  The
          `Result of Evaluation' will be displayed as "2.3979".

     (e)  To see if x is greater than 0, enter "x>0".  The
          `Result of Evaluation' is "1" (for TRUE).

     USING EXPRESSIONS IN FILENAMES  (Data Sequences)

     Both strings and filenames can utilize the expression parser
     to create unique "numbered" names.  The most common use for
     this is for reading and writing of data sequences.  The spe-
     cial character "$" is used as the delimiter.  As an example,
     suppose that you have defined the variable count and that
     the variable is being used in a COUNT_LOOP glyph.  The vari-
     able count can be used as a suffix on a filename in an input
     or output connection. This is done by typing in the file
     name result.$count.  When the visual program is run, it will
     produce files named result.1, result.2 ....

     VARIABLE DEPENDENCIES

     Variables are stored as expressions, rather than values.
     This allows expressions to be dependent upon each other,
     thus a change in one expression will be reflected in the
     dependent expression.

     Examples

     (a)  Set x equal to y, "x=y" in the `Enter Expression' win-
          dow.  Then set y equal to 10, "y=10".  If you check the
          value of "x" & "y" they will both show the value of 10.
          If you then set y equal to 5, "y=5", and check the
          value of "x" you should get that x is also 5.

     (b)  Another example where variable dependencies is useful
          is when trying to place icon image windows.  The exam-
          ple workspace in
          KHOROS_HOME/repos/workspace/vipl/normalize displays how
          to use the count loop variable to position the result-
          ing normalized image icons.  If a counter "i" incre-
          ments from 1 - 10 and the user wishes to automatically
          position the icons at five per row and two rows (or ten
          icons total).  Then they can define an "x" & "y" vari-
          able dependent on i, like the following expressions:
                     x = ((i-1) % 5) * 100
                     y = ((i-1) % 5) * 110 + 500
          The general form being as follows:
                     x = ((loop_variable - 1) % num_per_row) * width
                     y = ((int) (loop_variable - 1)/num_per_row) * height + y_offset

     SCOPE OF VARIABLES

     Variables and expressions defined in the top or main cantata
     workspace are global to all workspaces.  Subprocedures can
     prevent the use of global variables if the `Workspace'
     `Attributes' function `Use Global Variables' is set to "NO".
     If `Global Variables' is "YES" then the subprocedure will
     first check it's parents variables to see if the desired
     variable is defined there.  If not it will then search it's
     grand-parent's variable list.  This process is repeated
     until the main workspace is encountered or a workspace with
     Global Variables is set to "NO".  At which time an error
     will be displayed about the variable being undefined.

     Copyright 1991, University of New Mexico. All rights
     reserved.

Khoros                    Release: 1.0                          1

