RAFOS Float Setup Software V1.12
The available files are:
The source code is in C++ and has compiled and run in the following environments:
(MS-DOS users, will need the extra files in the directory DOS_Extras in order to build an executable from the source code. Note that this directory includes an MS-DOS version of cputime)
setup [options] [infile1 [infile2 ...] ]
It can read multiple files named on the command line, or will read from stdin if none are named. Any number of input files can be used.
setup -- will give a summary of the currently available options
Setup can also (optionally) read a run-time configuration file. If the file 'setup.rc' is in the working directory when the program is run, it will be read to set the desired options. Options that apply globally (that is to all floats) can be set either from the 'rc' file or the command line. If the option is set both ways, the command line setting overrides the configuration file setting (see below for an exception). The most useful feature of the configuration file is the ability to set parameters for individual floats. This allows processing of a mixture of 8 and 32 bit platforms in a single session.
The configuration file uses the following rules:
The '#' character is a comment, anything on the line after this is ignored.
The ':' character is a "go" character, it is used to inform setup that it should process all the parameters it has so far. The main use for it here, is to process individual float parameters before going on to another float.
Hexadecimal numbers are prefixed with 0x Octal numbers are prefixed with 0 Decimal numbers are the default
# # An example runtime control file for setup program # # verbose default_bits 8 # could be overridden by the command line fortran # write out FORTRAN binary file # # Now the individual float parameters # float 0x881 # remember to use HEXADECIMAL notation, otherwise # # the float number is read as decimal. bits 32 # NOT overridden by command line messages 100 : # signal the end of settings for this float float 0x888 messages 120 bits 32 : float 0x5335 # this float uses the default number of messages bits 32 : float 0x17304 bits 32 : float 0x2867 # this float defaults to 8 bits unless overridden messages 124 # on the command line # The ':' character at the end is Ok but not necessaryThe available options are:
automatic Run the program in automatic (not interactive) mode default_bits < number > The default number of bits for each platform fortran Generate FORTRAN binary output files headers Write message headers to the output stream verbose Set to verbose execution logfile < name > Log output to the given logfile name float < number > The Float number for following parameters bits < number > The number of bits for THIS platform messages < number > The number of ARGOS messages for THIS platform only < list > Only process the floats in the specified list (the list is delimited by spaces, commas or colons)A note on the interaction of the configuration file and the command line options:
The setup program parses the configuration file (up to the first ':' if any) before checking the command line. The result is that a command line option can override a configuration file setting. But all configuration file options set AFTER a ':' character are processed after the command line is completely parsed. So any configuration file settings made after a ':' will override the command line setting.
The following example configuration file is equivalent to the above one, except for two things. 1. Float 2867 will ALWAYS be 8 bits, no matter what the command line setting was, 2. The other floats default to 32 bits, unless the command line option set it to 8 bits.
verbose default_bits 32 # could be overridden by the command line fortran # write out FORTRAN binary file # # Now the individual float parameters # float 0x881 # remember to use HEXADECIMAL notation, otherwise # # the float number is read as decimal. messages 100 : # signal the end of settings for this float float 0x888 messages 120 : float 0x5335 # this float uses the default number of messages : float 0x17304 : default_bits 8 # set the global default to 8 bits float 0x2867 # this float defaults to 8 bits messages 124Message processing proceeds as follows:
Good checksum: -- dont already have it, accept it -- already have it and is same ignore it -- already have it and it is different write both to the log file and notify the user of TWO messages with good checksums. In automatic mode keep the oldest one, otherwise go interactive. Bad checksum: -- dont already have it, accept it with a bad checksum flag -- already have it and is same ignore it -- already have it and it is different write both to the log file and notify the user of TWO messages with bad checksums. In automatic mode keep the oldest one, otherwise go interactive.How setup handles message numbers greater than 255.
The latest FORTH MISSION ROMS ( either missiona.68 and, missionb.68 for source code or rom1.s1 and, rom2.s1 for compiled code) do an additional step in calculating the checksum if the message number is greater than 255. The high byte is also used in the checksum calculation, by going through the checksum loop one more time with the high byte of the message number. The transmitted message number is still the low byte, so the actual message number is: actual.msg_num = argos.msg_num + ? * 256
Where the ? is unknown, but can be inferred from the checksum by trying each possiblity ( 0, 1, or 2 -- larger than 2 will require a larger data buffer in the float). The value that gives a good checksum is probably (but not necessisarily) the correct value. A single message is tried for all possible locations. The selection algorithm for keeping the message is still the same as above, whether manual or automatic.
If you never specify the number of messages for a particular float (through the 'rc' file), then the float object will assume it has a maximum of 256 messages and it will automatically truncate to a smaller size if it gets a good message #0 (which contains the [low byte of] the total number of messages). Truncation will NOT occur if you specify the number of messages.
The output file is ASCII not binary. The file name is FLTxxxx.dat where xxxx is the hexadecimal float platform number. There is also an auxillary file FLTxxx.aux that contains information used by setup in case it is reinvoked on a particular platform (info about checksums and message numbers). The aux file COULD be useful for other processing programs (such as one to analyze the clock drifts). Setup will complain if there is a .dat file and no corresponding .aux file. If there is NO .dat file there is no problem (the code will assume that it is seeing a new float and build one, along with the corresponding .aux file).
If the FORTRAN output option is chosen, there will also be a file FLTxxx.bin, that is an unformatted FORTRAN file (this file is created by fwrite, which is called from within setup). Fwrite can be invoked from the command line if desired, see below.
I personally believe that ARTOA/ARGOT should be reorganized to read a cleaner ASCII file, something very much like the .dat file that this version produces.
The actions of setup are all written to a log file 'setup.log'. This file is appended to each time setup is run, so you have a complete log of all invocations of setup.
The log file also graphically shows the progress of building up the image of the float data buffer as follows:
Key to status information: + -- Good message - -- Bad Checksum message L -- Manually Locked message x -- Empty message ? -- Unknown statusNote the 'L' option for manually locked messages. This is useful if the operator knows that a particular message belongs in a certain location in spite of the checksum status. Locked messages are fixed and additional messages for that location are ignored if they are encounterd.
Float: 2867 256 total messages 0 xx+xx+x+xx 10 -x+xxxxxx+ 20 +-xx-xxxx+ 30 xxx--xxxxx 40 +xx+xxxxxx 50 xxxxxx-xx+ 60 xx-xx+xxxx 70 xxxxxLxxxx 80 +xxxxx+xx+ 90 +x-+xx+xxx 100 xxxx+x-+xx 110 x-xx-x+x+x 120 x-xxxxxxxx 130 x+x+xxxx+x 140 x-+xxxxxx- 150 xx-xxxxxxx 160 xxx+-xx+xx 170 xxxxxxxxxx 180 xxxxxxxxxx 190 xxxxxxxxxx 200 xxx-xxxxxx 210 xxxxxxxxxx 220 xxxxxxxxxx 230 xxxxxxxxxx 240 xxxxxxxxxx 250 xxxxxx Summary: 27 (10.5469 %) good, 17 (6.64062 %) bad, 211 (82.4219 %) empty, 1 (0.390625 %) locked
The FORTRAN program fwrite.f reads a '.dat' and an '.aux' file for a given float and will build the corresponding '.bin' file. The .bin file is a binary FORTRAN file, in the same format as the older FORTRAN version of setup. This will allow the unmodified set of follow-on processing code to be used.
Fwrite is automatically run internally within setup if the '-f' option is chosen (fwrite should be in the execution path in order for this to work).
Fwrite can also be invoked manually. It expects 3 file names on the command line:
fwrite datafile auxfile outfile
The program will fail (by design) if the output file exists.
You may need to modify the routines for accessing the command line. There is no standard FORTRAN method for accessing the command line, but most (but not all!) compilers provide some mechanism for obtaining it. Other than that, this program is written completely in FORTRAN-77.
A note about FORTRAN binary files. Normal (i.e. sequential) FORTRAN binary files are record oriented. Every write statement writes a single record. These records are delimited by an End-Of-Record marker (and often a Start-Of-Record marker). What bit pattern constitutes a Start-Of-Record mark and End-Of-Record mark IS COMPILER SPECIFIC, IT IS NOT SPECIFIED IN THE ANSI STANDARD. Any portability between such files is a coincidence and should not be counted upon. If you want to write binary files in FORTRAN and have any hope of portability (between compilers, languages and/or platforms) use DIRECT I/O, then the bits that are written to a file are only the ones that you have explictly asked to be written there.
Please try out the code and let me know what you think about
it so I can take your comments and use them to improve the
code for the next release.
Still To Do: Will need to deal with CRC vs. Checksum (at this point no RAFOS floats utilizing a CRC are being used, so this is a low priority).
Everett (Skip) Carter Phone: 831-641-0645 FAX: 831-641-0647
Taygeta Scientific Inc. INTERNET: firstname.lastname@example.org
1340 Munras Ave., Suite 314 UUCP: ...!uunet!taygeta!skip
Monterey, CA. 93940 WWW: http:/www.taygeta.com/skip.html
Skip Carter's Home Page
Please try out the code and let me know what you think about it so I can take your comments and use them to improve the code for the next release.