%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      createicat.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, CREATE/ICAT
%.PURPOSE    On-line help file for the command: CREATE/ICAT
%.VERSION    1.0  16-JAN-1990 : Creation, KB
%.VERSION    1.1  17-MAR-1992 : Update, KB
%----------------------------------------------------------------
\se
SECTION./ICAT
\es\co
CREATE/ICAT                                            23-FEB-2009  KB
\oc\su
CREATE/ICAT [catname] [dir_spec] [descr]
	create a catalog of images in the current directory
\us\pu
Purpose:
          Create a catalog of images in the current directory.
\up\sy
Syntax: 
          CREATE/ICAT [catname] [dir_spec] [descr]
\ys\pa
          catname = name of catalog, defaulted to `icatalog.cat'
\ap\pa
          dir_spec = file specifications as used in the VMS `$ DIRECTORY'
              or UNIX `$ ls' command;
              or table,label if the filenames are specified in a column of a 
              Midas table;
              or file.ascii if the filenames are specified in the records of
              ASCII file file.ascii (i.e. the file type must be `.ascii')
              if set to `NULL', the catalog is created without entries;
              defaulted to `*.bdf'
\ap\pa
          descr = name of char. descr. used for the Ident field in the 
              catalog records (you can sort the catalog according to the 
              Ident field);
              defaulted to IDENT
\ap\no
Note: 
             The file type of a MIDAS image catalog is `.cat' .
          The catalog contains for each image frame an entry with:
          sequence no., name, Ident field,Naxis, Npix(1), Npix(2), Npix(3).
          Ident field holds the contents of the descriptor `descr' given 
	  in the CREATE/ICAT command.
          The no. of entries in the created image catalog will be displayed 
          and also stored in the integer keyword OUTPUTI(10).
             If the catalog 'xyz' is the currently active image catalog (use 
          the command "SET/ICAT xyz" to do that), it is updated automatically 
          by Midas. I.e. creating a new image will also add a new entry to 
          the catalog, whereas the command ADD/ICAT has to be used explicitly 
          to add an entry to any other image catalog.
             An image with an entry in an image catalog can be accessed either
          via its name or via \#NO, where NO is its sequence number in the 
	  currently active image catalog, resp. via \#NO_catname, where NO is
	  its sequence number in the image catalog `catname'. 
	  E.g. use #13_myicat to access entry 13 in image catalog `myicat.cat'.
             Reuse the command CREATE/ICAT whenever your image catalog does
          not reflect anymore the actual directory because e.g. you executed
          some operating system commands like `$ COPY' (for VMS) or `$cp '
          (for Unix) !
             With the command STORE/FRAME you can loop over an image catalog
          in a Midas procedure in a straight forward way.
             Besides images the command CREATE/ICAT will also store entries 
	  for tables and Fit_files in the image catalog if so specified in
	  `dir_spec' (the main usage of this is the OUTTAPE/FITS command).
\on\see
See also: 
          READ/ICAT, SET/ICAT, CLEAR/ICAT, SHOW/ICAT, DELETE/ICAT
          ADD/ICAT, SUBTRACT/ICAT, SORT/ICAT, SEARCH/ICAT, PRINT/ICAT
          CREATE/TCAT, CREATE/FCAT, CREATE/ACAT
          STORE/FRAME, @a catalsync
\ees\exs
Examples:
\ex
          CREATE/ICAT
            Create the image catalog `icatalog.cat' with entries for all
            image files with filetype `.bdf' in your current directory. Use 
            descriptor IDENT for the Ident field of the catalog.
\xe\ex
          CREATE/ICAT torreon null
            Create the image catalog `torreon.cat' with initially no entries;
            entries may be filled via the ADD/ICAT command later on
\xe\ex
          CREATE/ICAT mazatlan n*.bdf
            Create the image catalog `mazatlan.cat' with entries for all image
            files matching n*.bdf, e.g. n.bdf, n123.bdf net.bdf ...
\xe\ex
          CREATE/ICAT mazatlan n*.bdf cunit
            As above, but use char. descr CUNIT for the Ident field of the
            catalog.
\xe\ex
          CREATE/ICAT juarez matamoros,:files
            Create the image catalog `juarez.cat' with entries for all image
            files stored in column :files of table `matamoros.tbl'.
\xe\ex
          create/icat guadalajara n*.bdf,z*
            Create the image catalog `guadalajara.cat' with entries for all
            image files matching n*.bdf and z* .
\xe \sxe
