% @(#)computtabl.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:22 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      computtabl.hlq
%.AUTHOR     MP, IPG/ESO
%.KEYWORDS   MIDAS, help files, COMPUTE/TABLE
%.PURPOSE    On-line help file for the command: COMPUTE/TABLE
%.VERSION    1.0  05-Aug-1992 : Creation, MP
%----------------------------------------------------------------
\se
SECTION./TABL
\es\co
COMPUTE/TABLE						05-Aug-1992 MP
\oc\su
COMPUTE/TABLE table column = expression
	compute arithmetic or string operations on table columns
\us\pu
Purpose:      
              Perform arithmetic or string operations on columns in a table. 
              The output column will be created if it doesn't exist.
\up\sub
Subject:      
              Table, column, arithmetic, string
\bus\sy
Syntax:       
              COMPUTE/TABLE table column = expression
\ys\pa
              table = table name
\ap\pa
              column = output column, either already existing or a new one
                       created by the command (In that case, the column has
                       to be referred to by label) .
\ap\pa
              expression = FORTRAN compatible expression , in
                       which the variables are columns in the table.

\ap\no
Note:         Expression may contain arithmetic operators, logical operators 
              and mathematical functions. 
              The supported arithmetic operators are +, -, *, / and **.
              The supported mathematical functions are :
\\
                     SQRT(:a)  LN(:a)   LOG10(:a)  EXP(:a)  SIN(:a) \\
                     COS(:a)   TAN(:a)  ASIN(:a)   ACOS(:a) ATAN(:a) \\
                     SINH(:a)  COSH(:a) TANH(:a)   ABS(:a)  INT(:a)  \\
                     MIN(:a,:b)  MAX(:a,:b)  MOD(:a,:b)            
\\
              Arguments of trigonometric functions are in degrees. The function
              INT produces the nearest integer value. The function MOD returns
              the floating-point remainder of a/b with the same sign as a.
\\
              The supported logical operators are .AND. .OR. .NOT.

              String operations can be performed on character columns:
\\
              TOLOWER(:a)  convert all characters in the column to uppercase
              TOUPPER(:a)  convert all characters in the column to lowercase
              COLLAPSE(:a) remove all spaces from the contents of the column 
              CONCAT(:a,:b)
              CONCAT(:a,s) concatenate the contents of two columns 
                           or of one column and one string into an output column

              The function TOCHAR(:a) can be used to convert the values of a 
              column with any numerical type into strings,  using the output
              FORTRAN format associated to the input column.

              The variable name SEQUENCE (short form SEQ) can be used as
              variable, refering to the sequence number of the table entries.
\\
              The variable name SELECT (short form SEL) can be used as 
              variable, refering to the select flag of the table entries 
              (The value will be 0 or 1 according to whether or not the
              entry is selected). This variable can be used to perform
              computations only on the selected entries of the table.
              Please, note, that for variables SEQUENCE and SELECT we should 
              NOT have a colon(`:') in front.
   
\\
              If the output column doesn't exist, it will be created and
              its type will be the same as the "highest" one of the input
              columns. 
\\
              The result of an illegal operation (i.e logarithm of a negative
              number) will be set to the NULL value. 
\\
              The SELECT mask will be reset by this command, i.e., before the
              computation, all the elements in the table are selected.
\on\see
See also:
              CREATE/COLUMN, WRITE/TABLE, SELECT/TABLE, COMPUTE/IMAGE
\ees\exs
Examples:
\ex
              COMPUTE/TAB mytable :MAG = 21.3-2.5*LOG10(:INTEN-:BACK)
                Compute for table `mytable.tbl' the resulting column :MAG from
                the expression involving the input columns :INTEN and :BACK.
\xe\ex
	      COMPUTE/TAB mytable :R = 0.5*SEQ
                Compute resulting column :R from the expression involving
                the sequence number of the table entries.
\xe\ex
              SELECT/TAB  mytable :MAG.LT.110.
              COMPUTE/TAB mytable :Z = MIN(:MAG,:R)+SEL
                Compute resulting column :Z as follows:
\\
                compute for each row the minimum value of the column :MAG and
                the column :R and add to the result the selection flag of the
                row.
\xe\ex
              COMPUTE/TAB mytable :NAME = CONCAT(:STAR,TOCHAR(:SEQ))
                For each row of the table myname, convert the value of the 
                column labeled :SEQ into a string, concatenate it to the
                contents of the column :STAR and store the result into the
                column :NAME.
\\
                Here we use a column labeled :SEQ not the sequence numbers!
\xe\sxe