PDS_VERSION_ID = PDS3 DATA_SET_ID = "MEX-M-MARSIS-3-RDR-AIS-V1.0" RECORD_TYPE = STREAM OBJECT = TEXT PUBLICATION_DATE = 2007-07-05 NOTE = " SOFTINFO.TXT describes the contents of this directory." END_OBJECT = TEXT END This directory contains files relating to example software applicable to the data on this volume. All code and files are provided "as is" (without support) The hope that they will be useful in understanding the data provided on this volume. [SOFTWARE] This directory | |- AIS_TESTIN.DAT Test input data for validating the program | |- AIS_TESTIN.LBL Label for test input data | |- AIS_TESTOUT.TXT Test output data for validating the program | |- READAIS.C Example source code to demonstrate reading MARSIS AIS | data sets | |- SOFTINFO.TXT Description of and instructions for software in this directory (this file). READAIS.C is a simple example program intended to convert the binary AIS Data set into a human readable ASCII format. The goals of the program are to illustrate how to access the data files and to provide something useful for those who wish to output the data to other software, such as a spread sheet. The AIS data set is stored in a simple binary format. Each data record is naturally aligned for performance reasons as well as compatibility with third party software. The record structure is show below. Byte 1 77 81 400 ---------------------------------- Record No. 1 | Status | FREQ | 80 Data Points | -------------------------------- Record No. 2 | Status | FREQ | 80 Data Points | ---------------------------------- ******************************** ---------------------------------- Record No. N | Status | FREQ | 80 Data Points | ---------------------------------- Status the instrument settings and time of capture. Freq the transmit frequency for the sounding event. Data a time series of 80 consecutive measurements captured directly following the sounding event. The units of measure are V*V/m*m/rtHz. An example of an output record is included at the end of this document. read_ais() - reads the binary Mars Express MARSIS AIS Data sets and produces an ASCII readable text. To compile the program under LINUX/Mac osX/Windows there are a few steps. It is assumed you have the GNU C compiler (gcc) already installed, if not, it is freely available on the web. Other compilers may work, but have not been tested with the code. If you encounter problems with other compilers, it may be necessary to correctly terminate each line of the program with either a for linux, for windows. Note for Mac Users: It may be the case, that Mac os9 has as it's standard, whereas Mac osX will tolerate either or when compiled with gcc. The following is a summary list of the commands to be executed. Each is explained in detail following this summary. $ cp READAIS.C read_ais.c # rename ".C" to ".c" # plus add underscores $ gcc read_ais.c -o read_ais # compile $ read_ais AIS_TESTIN.DAT > aisdat.txt # binary AIS to text AIS $ diff AIS_TESTOUT.DAT aisdat.txt # compare with the expected output Step No. 1: Renaming the Source Code with a Lowercase "c" Extension Rename the source code (READAIS.C) to something different with a lower case "c" extension (read_ais.c). Note there is an additional underscore in the file name. Some unix based file systems do not allow one to copy a file name that is uppercase to one which is lowercase, ie. Copying "FILENAME" to "filename" may fail on some systems, in particular (Mac osX). Secondly, some C compilers need a lowercase "c" to determine correctly identify the source code as C source code. Comments are provided after the "#" sign and should not be typed on the command line. The dollar sign "$" represents the command prompt and should not be typed. In windows, the command prompt looks something like "C:\". $ cp READAIS.C read_ais.c # rename ".C" to ".c" Step No. 2: Compiling the Source Code You may use any compiler you wish, as long as it compiles to ANSII C standards. Most modern compilers will do so by default. Comments are provided after the "#" sign and should not be typed on the command line. The dollar sign "$" represents the command prompt and should not be typed. In windows, the command prompt should be "C:\" (or other logical device name). $ gcc read_ais.c -o read_ais # compile If you had problems compiling the source code, make sure the extension is lowercase "c" and the line termination characters are appropiate for your operating system and the compiler you are using. The above file is line terminated with (0x0D 0x0A in hexadecimal). Step No. 3: Creating the ASCII Text Output You should now have an executable named "read_ais" in your current working directory. Provided is a test input for the program, binary AIS data, and a test output, text AIS data for comparison. Using the newly created executable, "read_ais", we will convert the binary AIS data to text AIS data. (Note: Make sure that the current working directory is included in your path.) Comments are provided after the "#" sign and should not be typed on the command line. The dollar sign "$" represents the command prompt and should not be typed. In windows, the command prompt should be "C:\" (or other logical device name). $ read_ais AIS_TESTIN.DAT > aisdat.txt # binary AIS to text AIS Step No. 4: Comparing with the Output The program should produce an ASCII text file of the AIS data. For comparison, the expected output has been provided in the file named "AIS_TESTOUT.TXT. Visually inspect the two files to see that the contents are the same or you may use the linux command below. Comments are provided after the "#" sign and should not be typed on the command line. The dollar sign "$" represents the command prompt and should not be typed. In windows, the command prompt looks something like "C:\". $ diff AIS_TESTOUT.DAT aisdat.txt # compare with the expected output In general, to run the program, $ read_ais FILENAME where FILENAME is the name of the binary archived data product or to read from stdin, (where "stdin is the Unix standard input) $ read_ais < FILENAME where FILENAME is the name of the binary archived data product and "<" is the Unix redirection operator that read a file and puts it contents ont stdin.