% @(#)createtabl.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:28 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      createtabl.hlq
%.AUTHOR     JDP, IPG/ESO
%.KEYWORDS   MIDAS, help files, CREATE/TABLE
%.PURPOSE    On-line help file for the command: CREATE/TABLE
%.VERSION    1.0  12-AUG-1984 : Creation, JDP
%.VERSION    1.1  04-Mar-1991 : New Table Version
%----------------------------------------------------------------
\se
SECTION./TABL
\es\co
CREATE/TABLE						12-AUG-1984   JDP
\oc\su
CREATE/TABLE  table ncol nrow file [format_file] [organization]
	create a table
\us\pu
Purpose:      
             Create a table and load values from a file. Format conversion
             is controlled by an auxiliary format file (.fmt).
             If the table contains only REAL*4 columns and no NULL values
             are present, the format file can be omitted.
\up\sy
Syntax:       
             CREATE/TABLE  table ncol nrow file  [format_file] [organization]
\ys\pa
             table      = the table name
\ap\pa
             ncol       = number of columns; * if ncol defined in format_file.
\ap\pa
             nrow       = number of rows;    * if nrow defined in format_file.
\ap\pa
             file       = file name, default type .dat with the ASCII info
                           to be loaded into the table (all lines of the 
			   ASCII file will appear as table rows, even if it
			   has more lines than parameter nrow. Then, additional
			   rows are allocated). The filename  NULL
                           produces an empty table (Disk Space is allocated 
                           no columns are created; use CREATE/COL to 
                           create them)
\ap\pa
             format_file = optional filename (type .fmt) used to define
                           the format of the ASCII file, and the size of the
                           table when ncol and/or nrow are *. By default the
                           name table.fmt is used. If the format file does
                           not exist, the conversion is done via list-directed 
                           input, free format. In this case the labels are
                           defaulted to LABxxx.
\ap\pa
            organization = optional file organization, as \\
                           RECORD (table stored row per row) or\\
                           TRANSPOSED (table stored columnwise) (default).
\ap\no
Note:        
\\
            The format file describes each field (column) in the
            table ASCII file as :
\\
            DEFINE/FIELD [pos1] [pos2] type [format] label [unit]
\\
            where
\\
            pos1 = starting position of the field
\\
            pos2 = last position in the field
\\
            type = data type of the field as I - integer,
                                             R - real single precision,
                                             D - real double precision,
                                             C - character.
\\
            format = optional FORTRAN format
\\
            label  = column label associated to that field
\\
            unit   = optional units

            Three keywords can also be added at the beginning of the format
            file:
            ROWS    number_of__rows (if not specified in the command line)
\\
            COLUMNS number_of_columns (if not specified in the command line)
\\
            FS      list of field separators used in the ASCII data file.
                    Only used when pos1 and pos2 are not specified in the 
                    DEFINE/FIELD statement. Per default tabs and blanks are
                    used as field separators. The list of separators has to  
                    be written in the form "f1f2f3". The number of field
                    separators is not limited. If the blank is used as field
                    separator, character strings containing blanks have
                    to be enclosed within double quotes.
\\                   
            Warning: Not all MIDAS commands will work on tables organized
                     in RECORD mode
\on\see
See also:
            CREATE/COL, CREATE/VIRTUAL, DELETE/COL, WRITE/TAB, EDIT/TAB COMPUTE/TAB
            SELECT/TAB, COPY/TAB, PROJECT/TAB, COPY/TT, MERGE/TAB
\ees\exs
Examples:
\ex
            CREATE/TABLE mytable 5 1000 myfile format
            Create the table mytable from ASCII data in the
            file myfile.dat, using the format in format.fmt
            The ASCII file myfile.dat could contain the following
            structure\\
\\{\tt
            .........1.........2.........3
\\
            123456789012345678901234567890
\\
            NGC 3379 10.75 12.85 E 893
\\}
            The associated file format.fmt is defined as:\\
\\{\tt 
            ! - format file 
\\
            DEFINE/FIELD 5  8  I      :NAME "NGC"
\\
            DEFINE/FIELD 10 14 R F5.2 :RA "HOUR"
\\
            DEFINE/FIELD 16 20 R F5.2 :DEC "DEGREE"
\\
            DEFINE/FIELD 22 22 C      :TYPE
\\
            DEFINE/FIELD 24 26 I      :RV
\\
            END
\\}
\xe\ex
            CREATE/TABLE veron 3 1000 veron veron
            Generates veron.tbl from the ASCII file veron.dat using
            the format file veron.fmt which is defined as:
\\{\tt
            FS = "\t,"
\\
            DEFINE/FIELD R    :RA
\\
            DEFINE/FIELD R    :DEC
\\
            DEFINE/FIELD C*13 :NAME
\\}
            No field positions are given, tabs and commas are used as field
            separators.
            The file veron.dat has the following structure:
\\{\tt
            0.0047,-35.0596    MS2357-3520
\\
            0.0286,-63.5943    MS2357-6352
\\
            0.0499,0.0401      Q 2357-0014
\\
            0.0528,-0.2427    Q 2357-005A
\\}
\xe\ex
            CREATE/TABLE table 4 100 data
            Generates table.tbl from the ASCII file data.dat without
            associated format file. The information in the file
            data.dat is in free format (list-directed read in
            FORTRAN) as\\
\\{\tt
            1000.0 4.3, 1.1      2.
\\
            1001.0 5.2  3.4      0.3
\\
            1020.1 2.5  1.2      3.
\\
            ........
\\}
\xe\sxe