CRaTER -- browse

NAME

browse -- takes several LRO-standard data files and time-merges them into a single output stream, either UDP packets (by default) or a file, slicing and dicing on the way.

USAGE

    browse [-a ###] [-c #] [-f basename] [-F file_ID] [-h]
            [-m machine_name] [-q UDP_port]
            [-s #:###] [-t|T #:###] [-u] [-v] filename1 [filename2 ...]

FLAGS

     -a ###   only output packets with the given AppId
                multiple -a flags are allowed
     -c #     set time compression ratio; default is 1
     -F       sets file_ID in LRO standard LO archive header; default is 202
     -f       writes LRO-standard LO archive to given name
     -l       list embedded echoes/commands; equivalent to "-f /dev/null -v"
     -h       prints this help message
     -m machine_nmae  machine to which UDP packets are to be sent [localhost]
     -q UDP_port      port to which UDP packets are to be sent [11403]
     -s #:### start output on this command echo in form of
           command_id:command_value.  If no command_id given, the
           echo command is assumed
     -t #:### stop output on this command echo; see -s flag
     -T #:### stop output and exit on this command echo; see -s flag
     -u       when reporting time, use UTC [local timezone]
     -v       verbose display

DESCRIPTION

Input

Given a set of LRO-standard data files, browse reads all in parallel and writes them into a time-ordered, single output file. Within a given one second interval, the input streams are read in the order given in the command line. If the input files are compressed, the /tmp directory is used to accumulate working uncompressed input data.

Packet Output

In this (default) mode the -c, -s, and -t flags are typically not used. Instead the output starts by emitting packets in real time and is controlled by keyboard entry. The following letters may be entered followed by a RET.

     C     continue at last speed setting
     L     speed up by 2x
     K     slow down by 2x
     J #   jump to next command # [ECHO]
     S     stop
     X     exit program
     ###   skip forward n seconds and stop
     -###  skip backward n seconds and stop
     =###  skip backward n seconds quietly and stop

A very large negative number will simply rewind the input to the beginning. An empty RET will advance the stream by 1 second also.

Each echoed command is written to STDOUT, even if the packets are not being written out (as in a skip). Since a negative skip is accomplished by rewinding the input files to the beginning, a single -1 command will result in all commands issued up to this point being (re)echoed. Using the syntax =### rather than -### will cancel this behavior.

File Output

Filtering of the input is handled by scanning for commands echoed in secondary science packets, starting/stopping output based on matches to the given flag arguments. The nominal format is

           Command_ID:Command_Value

See the Data ICD (32-02001) for the command list, and note that the numbers may be given in octal, decimal, or hex notation. If no Command_ID: is given, the ``echo'' command is assumed. The flow control is applied immediately upon reading a packet from whichever input stream contains secondary science data. The effect is that the output stream will contain the packet with the ``start'' echo, but will not contain the packet with the ``stop'' echo.

The -c flag works as a time-compression ratio; a value of 0.2 will cause the output to run 5 times slower than real time. Conversely, a value of 5 will cause the output to run 5 times faster than real time.

BUGS

There is an operating system limit on the number of open files any single process can access -- typically 256. Given more data files than this, the generation of intermediate products is called for.

The first packet of each input file is used to determine where the first-in-time data resides. If one of the input files has a sudden time step, strange things may appear in the output stream.

SEE ALSO

   rtlm
   csh -->> "limit descriptors n" to increase limit on open files

AUTHOR

Bob Goeke

RCS Information

$Id: browse,v 1.20 2009/03/27 13:31:56 goeke Exp goeke $