NAME

catobs - conCATenate files belonging to same OBServing period

SYNOPSIS

catobs [infiles=] <file_names> [parameter=value ...]

DESCRIPTION

catobs is used to concatenate LECS event list files (both, _rev and _lev types are supported) that logically belong to the same observing period into one larger sum file. For each input file it is checked whether a corresponding science HK file exists. If this is the case, the program creates a sum HK file as well. The primary and all Bintable extension headers of the sum files are essentially copies of the corresponding headers of the first file in the list of files specified for concatenation. All time related keywords, such as TSTOP, TELAPSE, etc. are updated where necessary to reflect the larger time coverage of the sum files. In addition, history keywords are added to the primary headers and the N_OBIS keyword value is set to the number of input files.

WARNING: The list of input files given as infiles is strictly processed from left to right. Therefore, to ensure a proper time order of the event list data in the sum file, the individual files have to be specified in the right temporal order, i.e., in ascending order of the values of the TSTART keyword. Also, the program expects the very last file in the infiles list to contain the largest time tag values. Under this assumption the values of various time-related header keywords in the sum events files are derived from the headers of this last file in the list. The compevfiles task can be used to obtain a list of compatible event list files in the proper temporal order. In fact, the output of compevfiles can be directly used as value for infiles as demonstrated in Example 2 below.

PARAMETERS

The following command line parameters are recognized by the program:

infiles = "" [string: list of existing event list files]

A blank, or colon-separated list of event files to concatenate. If blank is used as file name separator, the list has to be enclosed by "" in order to be considered as a single command line argument. Note that the files are strictly processed from left to right and, consequently, have to be in the proper temporal order (see Warning note above). If a file in infiles does not exist or is found to be impossible to be appended to the sum file, a warning message is issued and the processing continues with the next file in the list.



indirpath = "" [string: list of directory names]

A colon separated list of directories to seek for the specified input files. For each file given in infiles this is performed by first attempting to open the file as specified in infiles. If this fails, each directory component in indirpath is inspected for the location of the desired input file.



stemoutfile = "-" [string]

This determines the file name stem of the sum file(s) to be created. The stem of a file name is defined to be everything before any extension _???.fits, e.g., the name stem of kv492_rev.fits is just kv492. Specifying "-" for stemoutfile means that the actual value shall be derived from the name of the first file in the infiles list which is expected to follow the naming scheme used by the FOT ingestor foting:

     <Stem>_<FOT_ID>_<Instrument_ID>_<ObsID>_<Number>_rev.fits

If the first file is found to match this pattern the sum file will get the name

     <Stem>_<FOT_ID>_<Instrument_ID>_rev.fits

otherwise, sum_rev.fits.



outdir = "=" [string: name of existing directory or "="]

The name of a directory to which the output file(s) shall be written. "=" means that the resulting sum file(s) shall be created in the directory the very first file in the infiles list was found. Note that write access to outdir is needed.



hkconcat = yes [boolean: yes|no]

If set to "yes", for each input event file it is checked whether a corresponding science HK file exists. If this is the case, a concatenated version of all single HK files is created similar to the event list sum file. "no" as value suppresses the HK sum file creation.



rmfiles = no [boolean: yes|no]

If set to "yes", the individual input files are removed after the corresponding sum file(s) has/have been successfully created.



printstem = no [boolean: yes|no]

If set to "yes", this triggers that the program does nothing but merely prints out the filename stem of the sum file and exits successfully.



verbosity = 2 [integer: 0|1|2|3]

Specifies the program verbosity level, i.e. the amount of screen output that will be issued during program execution. Level 0 means "mute", only fatal error messages will be printed. Verbosity level 3 results into detailed diagnostic messages. Default is level 2.



help = no [boolean: yes|no]

A boolean flag which, when set to yes triggers that the program prints out a brief on-screen description of all available command line parameters together with the current program version number and exits successfully.

EXAMPLES

1. Concatenate the three event files 1_rev.fits, 2_rev.fits, and 3_rev.fits. The resulting output file shall be named 123_rev.fits:

        catobs "1_rev.fits 2_rev.fits 3_rev.fits" outfile=123_rev.fits
   

2. Concatenate all event list files that are compatible with the file kv467_rev.fits using the task compevfiles. The sum file should get the default name. HK file concatenation shall not take place and the individual input files shall be removed after the sum file has been successfully created:

        catobs "`compevfiles kv467_rev.fits`" hkconcat=no rmfiles=yes
   

FURTHER DOCUMENTATION

1. The SAX LEGSPC Data Analysis System - Software User Manual,
   U. Lammers, Doc. SAX/LEDA/0010

BUGS

None known.

SEE ALSO

compevfiles,