RAFOS Float Setup Software V1.12

The available files are:

A PostScript version of the RAFOS Float FORTH glossary is also available here.

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)

To use the program, type:

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 necessary
The 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 124
Message 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 status


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
Note 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.

FWRITE:

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.

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).

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. 

 Everett (Skip) Carter          Phone: 831-641-0645 FAX:  831-641-0647
 Taygeta Scientific Inc.        INTERNET: skip@taygeta.com
 1340 Munras Ave., Suite 314    UUCP:     ...!uunet!taygeta!skip
 Monterey, CA. 93940            WWW: http:/www.taygeta.com/skip.html
Skip Carter's Home Page