%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2007 European Southern Observatory
%.IDENT      selecttabl.hlq
%.AUTHOR     MP, IPG/ESO
%.KEYWORDS   MIDAS, help files, SELECT/TABLE
%.PURPOSE    On-line help file for the command: SELECT/TABLE
%.VERSION    1.0  15-JUL-1992: Creation, MP
%----------------------------------------------------------------
\se
SECTION./TABL
\es\co
SELECT/TABLE                                            29-JUN-2007  MP

\oc\su
SELECT/TABLE     table logical-expression
	select table entries
\us\pu
Purpose:    
            Select table entries and save the no. of selections and
            all selected rows in integer descr SELIDX of table.
\up\sy
Syntax:     
            SELECT/TABLE table logical-expression
\ys\pa
            table = table name
\ap\pa
            logical-expression = a FORTRAN-like logical expression
                   enabling the user to define a subtable
\ap\no
Note:       
            The subtable will be used by commands that do not modify
            the table information, namely:
                PRINT, PLOT, OVERPLOT, STATISTIC, COPY (input),
                MERGE (input), PROJECT, READ, REGRESSION
            The selection criterion will be reset to the whole table
            by commands which change the table information:
                COMPUTE, SORT, COPY (output), MERGE (output), WRITE
            or by the logical expression ALL.
            Variables in the expression are columns defined by label or
            number, the sequence number of the entries in the table is
	    referred to via the name SEQUENCE (abb. SEQ)  NOT via :SEQ 
            and the logical  variables SELECT and ALL to include the 
            previous  select mask or the complete table resp. 

            The reserved name  NULL (for numerical cols) can  be  used 
	    with the relational operators  .EQ. and .NE.
            For char. columns the reserved name  "NULL" or "" should be
	    used to test for NULL values with .EQ. and .NE.

            Expressions may contain arithmetic, relational and logical
            operators and functions. The supported arithmetic operators are
            +, -, *, /, and **. Relational operators are:\\
                     .LE.  .LT.  .GE.
                     .GT.  .EQ.  .NE.\\
            Logical operators are: .AND. .OR. .NOT.
            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)\\   
            Angular units of trigonometric functions are degrees.
            In selections involving columns with floating numbers
            one should avoid expressions like :COLUMN.EQ.value; in this
            case the expression ABS(:COLUMN-value).LT.epsilon is
            recommended.
	    OJO: For single floating point values with a rather short
	    format (e.g. F5.3) the display may deceive you by dropping
	    digits and a selection may seem to give wrong results...

            One can select entries of a column  containing character strings
            which  match a pattern . The following special characters may be
            used to build these patterns:\\
            *     Wildcard character, replaces 0 to N characters\\
            ?     Replaces 1 character\\
            []    matches n alternative characters\\ 
            ~     Ignores case
            Be careful if blanks are in your selection criteria, as they 
	    might be interpreted as separators of parameters and not appear in
	    the selection criterion anymore e.g. 
	    select/table test :a.eq." *" .or. :a.eq."" would work correctly, 
	    whereas 
	    select/table test :a.eq." *".or.:a.eq."" 
	    will erraneously be interpreted as :a.eq."*".or.:a.eq."" leading to
	    the selection of the whole table.
                   
            The number of selected rows, NoSel (may be = 0), in the table is
            stored in the keyword OUTPUTI(1).
            The no. of selections, NoSel, as well as the indices (no's.) of 
            all selected rows will be stored in an integer descriptor, SELIDX,
            of the table.
            Thus, SELIDX(1) = NoSel, SELIDX(2),(3),...  the selected row no's.
            If ALL rows are selected, SELIDX(1) is set to -1, and the other
            elements of SELIDX are irrelevant.

            OJO: This descr. SELIDX could become really big depending on
            the size of the table and the no. of rows selected.
	    This descriptor SELIDX will be copied by every table command which
	    creates a new output table (e.g. COPY/TABLE) and thus may slow down
	    execution of the command. 
	    Also, the conversion to  and from FITS could become slower...
            Via SET/MIDAS SELIDX=YES/NO you can en/disable the writing of
            that descriptor - it's defaulted to YES (for backw. compatibility).

            The indices of the selected rows (but NOT NoSel) will also be 
            stored in a global integer keyword, MID$SELIDX, if this keyword has
            been defined before calling SELECT/TABLE. 
            The no. of elements in this integer keyword determines the max. 
            number of protocolled rows.
            The selection flag of a given row of a table may be read and copied
            into a keyword using the syntax: KEYWORD = 'table,sel,row'

	    SELECT/TABLE can also be applied directly to FITS tables, but
	    the saving of selection indices in descr. SELIDX must be enabled
	    for this to work (it's the default, see above).

	    OJO: Watch out for numerical comparisons with columns of "short"
	    formats, e.g. R f5.3, since internally these values are stored
	    with more precision - better use format D f5.3 in such a case.
\on\sa
See also:
            COMPUTE/TABLE
\as\exs
Examples:
\ex
            SELECT/TABLE mytable :MAGNITUDE.GT.7.0 
              Select all entries of the table `mytable.tbl' for which the value
              of the column MAGNITUDE is greater than 7.
\xe\ex
            SELECT/TABLE mytable .NOT.SELECT.AND.:Y.GT.0 
              Select all entries of the table `mytable.tbl' which were not 
              selected in the last SELECT command and for which the value of
              the column Y is greater than 0.
              Assuming, 17 rows have been selected, the descr SELIDX of
              `mytable.tbl' would contain 17,r1,r2,...,r17 with ri the row no.
              of the ith selected row.
\xe\ex
            SELECT/TABLE mytable ALL 
              Select the whole table. Keyword OUTPUTI(1) holds the total no. 
              of rows of `mytable.tbl' and descr SELIDX(1) = -1.
\xe\ex
            SELECT/TABLE mytable SEQ.eq.3
              Select 3rd row of table `mytable.tbl'.
\xe\ex
            SELECT/TABLE mytable.tfits SEQ.eq.3
              Select 3rd row of FITS table `mytable.tfits'.
\xe\ex       
            SELECT/TABLE mytable :STRING.EQ."S*7[ab]" 
              Select entries of the table `mytable.tbl' for which the contents
              of the column STRING match the following pattern:
              the char. string should start with S and end with 7a or 7b. 
\xe\sxe
