%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2008 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						10-APR-2012   JDP,KB
\oc\su
CREATE/TABLE  table ncol nrow data_file [format_file] [organization]
	create a table from ASCII data
\us\pu
Purpose:      
          Create a table and load values from an ASCII data file.
          Format conversion is controlled by an auxiliary format file.
          If the table contains only numerical columns and no NULL values
          are present, the format file can be omitted.
\up\sy
Syntax:       
          CREATE/TABLE  table ncol nrow data_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 data to be
                 loaded into the table 
                 All lines of the ASCII file will appear as table rows, 
                 even if it has more lines than the 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 later)
		 First char. # indicates comment lines.
\ap\pa
          format_file = optional filename (default type .fmt) to define
                 the format of the ASCII data 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,
                 and 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).
                 !OJO! Not all MIDAS commands will work on tables organized
                       in RECORD mode.
\ap\no
Note:        
          All lines of the data file beginning with the char. `#' or `!'
          are interpreted as comment and ignored.
 
          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.

          The max. no. of columns is set to 256. If you really need tables 
	  with more columns, you have to update the definition of
	  MAXCOL in the file /midas/version/prim/table/libsrc/tbaload.c
	  (look for the line starting with "#define MAXCOL ...").
	  The safest option is to reinstall Midas after you've done your
	  changes.
\on\see
See also:
          CREATE/COLUMN, CREATE/VIRTUAL, DELETE/COLUMN, WRITE/TABLE
          COMPUTE/TABLE, SELECT/TABLE, COPY/TABLE, PROJECT/TABLE, 
          COPY/TT, MERGE/TABLE
\ees\exs
Examples:
\ex
          CREATE/TABLE mytable 5 1000 myfile format
            Create the table `mytable.tbl' from ASCII data in the
            file `myfile.dat', using the format in `format.fmt'
            The ASCII file `myfile.dat' could contain the following
            structure
            .........1.........2.........3
            123456789012345678901234567890
            NGC 3379 10.75 12.85 E 893
            The associated file `format.fmt' is defined as:
            ! - 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 waldi 3 1000 waldi waldi
            Generates `waldi.tbl' from the ASCII file `waldi.dat' using
            the format file `waldi.fmt' which is defined as:
            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 `waldi.dat' has the following structure:
            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:
            1000.0 4.3, 1.1      2.
            1001.0 5.2  3.4      0.3
            1020.1 2.5  1.2      3.
            ........
\xe\sxe
