% @(#)createicat.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:27 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.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                                            30-DEC-1996  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 catalog is `.cat' . The catalog contains
          for each image frame an entry with:
\\
          sequence no., name, Ident field (which is the content of descriptor 
          `descr' ) and values of Naxis, Npix(1), Npix(2).
\\
          The catalog `xyz' is updated automatically by the system, if the
          catalog is the currently active image catalog (use the command
          "SET/ICAT xyz" to do that). I.e. creating a new image frame 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 can then be accessed either via its name or via \#NO ,
          where NO is its sequence number (if it's in the currently active
          image catalog), resp. via \#NO_catname, where NO is its sequence
          number in the image catalog `catname'.
\\
          Use the command CREATE/ICAT whenever your catalog does not
          reflect the actual directory because you executed some operating
          system commands like `$ COPY' (for VMS) or `$cp ' (for Unix) !
\\
          The no. of entries in the new image catalog will be displayed and 
          also stored in the integer keyword OUTPUTI(10).
\\
          Besides images this command will also store entries for tables and 
          Fit_files in the image catalog if so specified in `dir_spec' (the
          main usage of this will be the OUTTAPE/FITS command).
\\
          With the command STORE/FRAME you can loop over a catalog in a Midas
          procedure in a straight forward way.
\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