TRACE Frame and Sequence Software

under construction....

The material on this page will be of no interest or utility unless you are involved in preparing frames and sequences for TRACE.

You need an account on diapason to run the software described below.

TRACE Frame Generator

This is a motif based interface for inspecting, generating, and saving TRACE frame definitions. The major catagories of parameters are organized into blocks. Previously generated frames can be loaded into the widget and then modified and saved to quickly make variations of old frames. To use this tool you need to be using X windows with Motif and be logged on to diapason or one of the other SGI's connected to diapason. Remote users need to set the environmental variable DISPLAY to their local device after logging on diapason. Then just type "traceframe" and the tool should pop up on your screen. For example, a user on shimmer would enter (from a terminal shell):

shimmer% rlogin diapason
password: xxxxxxx

diapason% setenv DISPLAY shimmer.space.lockheed.com:0.0
diapason% traceframe

The program will generate some messages in the Unix shell it was launched from (mostly debug clues) so running it in background is not recommended since it might be confusing.

The most common error using tracframe is having the wrong output path! Please read and understand the following paragraph.

Note that the output path for saved results is in a text box near the bottom right hand side of the widget. Be sure this is properly loaded with your desired output path. It is preloaded with the value of the environmental variable TSW_FRAME_OUT_DIR which you can define in your .cshrc file. The default value for TSW_FRAME_OUT_DIR will otherwise be /hosts/diapason/data13/trace_egse_sw/obs_dev.

Prototype TRACE Frame Display

Although they are generated as ASCII files, TRACE frames are not easy to decode. The critical part is just 256 bits listed as 16 hex values. The rest consists of some comments and keywords used only by the ground system. A small program called show_frame can be used to decode the hex words into a text description. This is just a small C program that uses standard input and output so it can be easily used in a script. It can also be easily re-compiled on any UNIX system and most others that have a C compiler. It does not use X or Motif. From diapason and most SGI's connected to diapason there is an alias to the program called showframe. For example:

shimmer% show_frame < trace_frame.00001

TRACE camera frame definition, created Aug 6, 1996 23:30:26
ID: 1
wave: Fe IX 171 open,open
exp: 0.010 seconds
events: SF(10000, 30), FF(1000, 20), T(110, 10)
subarea 1 used for events and I max, I min
I max generated
t avg: full camera read area, 11 image average
CCD: default amp, full camera 8x8, bin = 2
not saved
area 1: 256 x 256, bin = 4, I max center, offset (-128, -128)
save to main buffer, JPEG(10, 2, 3)
area 2: 512 x 1024, bin = 2, camera center, offset (100, 200)
save to main buffer, packed 12 bits

Here the file named "trace_frame.00001" is read and the text displayed in the shell (standard output). To output to a file, use:

shimmer% show_frame < trace_frame.00001 > text.file

where the result will just be written to a file called text.file.

The program also accepts command line arguments as input and output files as an alternative to using standard input and output. When present, the first command line argument is used as the input file and and the second (if also present) is used as the output file. Hence the above example could also be written as:

shimmer% show_frame trace_frame.00001 text.file

The sources for showframe are (from diapason) on /hosts/shimmer/usr/people/shine/trace in files:

show_frame.c
startbits.h
numbits.h

If you need to recompile this on another UNIX system, just grab the files and enter "make show_frame" on your computer (assuming you have a C compiler).

TRACE Sequence Compiler

The TRACE sequence compiler is used to compile user written command sequences for operating the TRACE instrument. It is normally used as part of the daily load generation but can also be used to test or verify a single sequence or just a few lines typed in. It does not have a widget interface and operates with standard i/o like a shell utility, accepting a few key arguments and a list of input files or reading from standard input (which allows redirection and piping). Inputs are text files containing sequence code and the output is a text file(s) of the meta-code used on board TRACE. The latter looks like assembly language. A document describing the sequence language is available by clicking here. There are now two versions of the parser because of some changes in the command generation process and a desire to keep the "old" method alive just in case. The old parser is /tsw/ana/parser (this is not ana code, just happens to be in that directory) and the new one is /tsw/ana/parser2. parser2 is mostly compatible with the old one but has more ability for handling lists of sequences. Together with makeload, it makes the command generation process very efficient compared to the previous method with topsdb. The two versions have aliaii on the TRACE account of traceparser and traceparser2. These are used below instead of the paths. Only traceparser2 is descibed below.

The possible command line arguments are: 

traceparser2 [-e] [-f] [-t] [-a] [-r] [-v n] [-x[l]] [-l list_file]
       [-s sym_file] [-o out_file] [-i input_file] input1 input2 ...

When used for a daily load, the call would be something like: 

traceparser2  -l my.lst -f -r -t -x -i all2_cck.slst

Where the file "all2_cck.slst" would contain a list of top level sequence names for the day. One could also use this to test newly written sequences but the -x option should be omitted or replaced by -xl (details about -xl below). With these options, all of these sequences (which are "useq" files) plus any called by them would be compiled. The results would be written as "seq" files. Also, a list of all sequences and frames would be written to the file "my.lst". Since these are the important options, they are described below first:

-l causes a list of all sequence and frame names to be written to a ASCII file with the name in the next argument. The name is taken as is, no path is added to it.

-f causes any error to immediately stop the program. When used together with -e (echo, see below), the offending line will also be the last line echoed. Without -f, the "bad" sequence stops compiling but any other sequences in the list are then compiled. The resulting output could then be grep'ed for errors to find all bad sequences.

A standard set of parameter definitions is read in when the -t key is used. These are files that specific the id's for frames, sequences, and targets. There is also a file defining lists and various aliaii. The file name path is defined via the environmental variable TOPS_DBASE_PATH and the individual names are: 


id_map_frm.tab
id_map_seq.tab
id_map_trg.tab
list_expand.tab

Note that if a sequence or frame is defined multiple times in one of these files, the last definition is used. Hence, the files can be simply appended when new version numbers are defined.

The "resolve" option, using the -r key, keeps a list of all sequences called and when the input files are compiled, any sequences that have been referenced but not compiled yet are searched for. If found, these are also compiled and any that they call are searched for. The process repeats until all sequence trees are completed unless there is an error along the way.

The -x option causes the compiled form of sequence to be written out as a "seq" file in the same directory as the "useq" file read in. This option can be given as -xl instead which causes the "seq" file to be written in the default directory instead. This is useful for testing.

The -i option takes the next argument as a "slst" file name. This is a file with a list (one per line) of the top level sequences to be compiled. Comments are allowed in the file in the form of #'s, //'s, or semi-colons. The names may have the useq attached. It gets stripped off if present and then ".useq" is attached to each name for file reading. Note that no version numbers are included in the names. The present rule is that the file that ends in just ".useq" (or ".ufrm" for frames) is the most recent version. Each sequence name is then searched for using the environmental variable TOPS_PATH as the root path. The sequence can be in any subdirectory of TOPS_PATH. The "seq" will be put in the same directory if the -x option is specified.

When the -i option is used, there should not be additional input files in the command line.

The remaining options are generally useful only for testing single sequences or debugging.

The optional -e turns on input echo and the option -o can be used to specify an output file (otherwise output goes to stdout which is your terminal or wherever you might redirect it). The -t key is used to preload standard tables (described below), -a causes a full symbol dump at the end of the file, and -s is used to specify a file for the used symbols table. Otherwise it goes to the output file. The -r key is used to compile any additional sequences that are called within the sequences specified. This is described in more detail below.

The input echo causes all input text (including comments) to be printed in the output file before each line is compiled. This text has a semi-colon at the beginning of each line so that it looks like a comment to the meta-code interpreter.

When not using the -i option, up to 20 input files can be included in the argument list. They are compiled in the order specified. Hence files that define parameters needed for other sequence files, should be first in the list. Normally a file containing the target and frame definitions of the day would be the first file input. If and only if there are no input files on the command line, the parser will read from standard input.

A separate used symbols file can be specified with the -s key. Otherwise it goes to the output file which was specified by th e -o key or just to stdout. The used symbols tables indicate all names of frames, sequences, targets, and lists actually used. This is separate from the list file generated by the -l option. The -l option generates a simple list for makeload.

The -v option is used to pass a version number and is only for compatibility with the older topsdb method of making loads. In general, it should no longer be used. The version number passed is encoded in the lower 4 bits of the sequence ID. Beware! The same version number would be used for all compiled sequences if there are multiple input files. It only makes sense to use this when handling a single sequence. Version numbers will be used when sequences are registered.

To use this parser on diapason (or another SGI connected to diapason) on a sequence file named flare2.useq and put the result to a file named flare2.tmc, use: 

diapason% traceparser2 < flare2.useq > flare2.seq
to do the same thing with an echo and writing to output file "output.load", use: 
diapason% traceparser -e -o output.seq < flare2.useq

An example using several input files is: 

diapason% traceparser -e -o output.load  defs.useq flare2.useq flare1.useq

Note that the name for the output file must immediately follow the -o key. The input file names can be before and/or after the optional -e and the -o filename arguments.

The source code for the compiler is written in lex and yacc and will compile on most UNIX systems that support C. The sources and makefile are (from diapason) on /hosts/shimmer/usr/people/shine/trace in files:

lex.l
parser.h
parser.y
makefile

If you need to recompile this on another UNIX system, just grab the files and enter "make parser" on your computer (assuming you have a C compiler). The executable will be in a file named "parser".

Page maintained by Dick Shine (shine@shine.space.lockheed.com)
Web Curator: Neal Hurlburt (hurlburt@umbra.space.lockheed.com)