% @(#)selecttabl.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:56
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 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-2000  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  can  be  used with the relational 
            operators  .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.
            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. 
	    sel/tab test :a.eq." *" .or. :a.eq."" would work correctly, 
	    whereas 
	    sel/tab 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 upon
            the no. of rows selected. This huge descriptor will be copied in
            every table command with a new output table (e.g. COPY/TABLE)
            and thus slow down execution. Especially, the conversion to FITS
            will become very SLOW and give you time for many coffees...
            So, it might be best to delete this descriptor before going on.
            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'
\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 :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