Langley DAAC Version Number: LD_008_020_001_00_00_0_19990407 SAGE I Aerosol Profiles Readme 1.0 Introduction This document contains information on running and compiling the read software for the Stratospheric Aerosol and Gas Experiment (SAGE) I and II profiles. There is read software available for: SAGE I Aerosol Profiles data set The SAGE I data set is only available in the Hierarchical Data Format (HDF). Section 2.0 - describes sample programs (source files). Section 3.0 - discusses how to create the executable from the programs. Section 4.0 - demonstrates how to invoke the run-time executables. Section 5.0 - provides general information on all of the data sets. Section 6.0 - provides more detailed implementation notes. If users have questions while using the SAGE I and II sample read software, please contact the Langley DAAC User and Data Services office at: EOSDIS Langley DAAC Science, Users and Data Services Office NASA Langley Research Center Mail Code 157D 2 South Wright Street Hampton, Virginia 23681-2199 U.S.A. E-mail: support-asdc@earthdata.nasa.gov Phone: (757)864-8656 FAX: (757)864-8807 2.0 Read Software File The sample read program for the SAGE data sets are developed in the C language (to read HDF data files). The C program has been tested on Sun (Solaris 2.5), Dec Alpha V4.0A, SGI Irix 6.2, and HP UNIX-based workstations. All library functions in the C source code are tested for ANSI C conformance. To generate the read software for the SAGE data, the HDF library and include files must be linked at compilation time. A compilation script is included for the convenience of creating the executable files from the source files. These files and their purposes are listed as follows: compile_sage1_read - contains a set of commands to build the run-time executable for reading the HDF data. read_sage1.c - reads the HDF SAGE I Aerosol Profiles, SAGE II Aerosol Profiles, SAGE II Ozone Profiles, SAGE II Nitrogen Dioxide Profiles, and SAGE II Water Vapor Profiles data. 3.0 Creating Executable Files The following sections describe how to create the executables for the HDF, ASCII, and binary formats. 3.1 Creating the Executables for the HDF data format files The user has two methods of building the sample read programs from the source files. The user is able to build the code from the command line or for conveince, build the code using the C shell script that was provided with the sample read software. All files are defined in Section 2.0. Users working with the HDF data format files need the HDF libraries in order to build the executable for the sample read software. HDF information, documentation, tutorials, libraries, etc. can be found on-line at the URL: http://hdf.ncsa.uiuc.edu A utility (hdp) is provided in the HDF libraries which will extract information about the contents of the HDF file. The commands: hdp -H hdp dumpsds [-options] hdp dumpvd [-options] vshow [+|+vdata_id] These will give information as to the size, type, and names of the HDF data structures. The [-H] option will give help information. Download the HDF libraries from the NCSA web site ( http://hdf.ncsa.uiuc.edu ). This code uses Version HDF4.1r2. Other versions of the HDF libraries may not work with this code. NCSA uses the gnu gzip compression utility for some packages. If you do not already have this software which is needed to uncompress the file, you can obtain it from one of the Gnu mirror sites listed at http://www.gnu.org/order/ftp.html Once all of the HDF libraries are located on your system, you are now ready to compile the sample read software. Currently, the Langley DAAC is working with Versions 4.1r1 and 4.1r2 of the HDF library. 3.1.1 Create an executable using the C shell scripts The files that contain the C shell scripts are those files that begin with the word "compile" in the file name. To build the executable that reads the HDF data format files for the SAGE I Aerosol data set, you must obtain the file script "compile_read_sage1." Refer to (edit) the sample script 'compile_read_sage1' to link the HDF libraries and compile the C program. Check the permissions on this file to make sure execute permission is set for the owner: ls -l compile_read_sage should display something like -rwxr--r-- 1 OWNER GROUP 4157 Jan 14 00:42 compile_read_sage1 where OWNER and GROUP are the file owner and group information. The owner executable permission is the x in -rwxr--r--. To set proper permissions (assuming you are the file owner), type chmod 744 compile_read_sage1 Execute the script 'compile_read_sage1' to create the executable by typing source compile_read_sage1 or, on some systems you need only type compile_read_sage1 To run the executable at the command line, just type: read_sage1 3.1.3 Create with the compiler This method uses the combinations of the HDF libraries, the HDF includes files, and the programs provided for the data sets (read_sage1.c). To build the executable for these data sets, at the command line prompt type: On your Sun system, the following command was used to build the sample software: gcc -o read_sage1 read_sage1.c -I/usr/local/hdf/include \ -L/usr/local/hdf/lib -lmfhdf -ldf -ljpeg -lz -L/usr/lib NOTE: You will have to modify the paths for the HDF libraries to the correct location on your system. On your SGI Irix 6.2 system, the following command was used to build the sample software: cc -ansi -n32 -mips3 -O -s -o read_sage1 read_sage1.c \ -I/usr/people2/paula/HDF/4.1r2_irix6.2/include \ -L/usr/people2/paula/HDF/4.1r2_irix6.2/lib -lmfhdf -ldf -ljpeg -lz NOTE: You will have to modify the paths for the HDF libraries to the correct location on your system. Also, when you compile the code, you will get some warning messages stating that all of the libraries expressed in the compilation call when not used. Just disregard those warning messages. You will still get the executable. On your Dec Alpha V4.0A system, the following command was used to build the sample software: cc -o read_sage1 read_sage1.c -I/usr/local/HDF4.1r1/include -L/usr/local/HDF4.1r1/lib -lmfhdf -ldf -ljpeg -lz -L/usr/lib NOTE: You will have to modify the paths for the HDF libraries to the correct location on your system. On your HP system, the following command was used to build the sample software: gcc -o read_sage1 read_sage1.c -I/usr/local/HDF4.1r1/include -L/usr/local/HDF4.1r1/lib -lmfhdf -ldf -ljpeg -lz -L/usr/lib NOTE: You will have to modify the paths for the HDF libraries to the correct location on your system. Remember that your paths on your system may be different than these listed above. Please modify your paths accordingly. 4.0 Invoking Read Software This section illustrates the invocation of the executable file. Section 6.0 describes how to run the read program for the SAGE I data set. 4.1 Invoking the HDF Read Software Data Set Read Software Executable Name -------- ------------- --------------- SAGE1_AERO_PRF read_sage1.c read_sage1 The HDF read program is able to read SAGE I Aerosol Profiles data. The executable prompts the user for the particular data set to read and the filename of the data set (including the pathname). To execute the program, at the command line prompt type: read_sage1 read_sage1 will read the HDF data and send the output to a file with the same name as the input file but will include a ".rpt" extension. This report file will be written in the working directory. The program will then prompt the user to select which parameters to output to the report file. This assumes that the data input files are located in the current working directory as well. For example, if the input file is 'sag1_aer_prf_7902,' the output will be written to the file 'sag2_aer_prf_7902.rpt.' A customized menu has been provided to enable the user to select parameters. See Section 6.0 IMPLEMENTATION NOTES for an actual run of the code. 5.0 Data Sets Information Currently, the read program, read_sage1.c, is able to read five data sets, SAGE I Aerosol Profiles, SAGE II Aerosol Profiles, SAGE II Ozone Profiles, SAGE II Nitrogen Dioxide Profiles, and SAGE II Water Vapor Profiles. The following subsections describe these five data sets. The information on these data sets were obtained from text files or documents from the data producer. The high-level data set descriptions, the data files, the variables in the data files, and the contacts for data production are given under each data set. NOTE: There are two parameters in these data files called Number Density Quality Bit Flag and Volumetric Mixing Ratio Quality Bit Flag. These values are actually written into the hexidecimal format. This means that code and users must be careful in reading and/or writing and/or working with these data values. Because these are hexidecimal values, you must read them as unsigned 16-bit integers. 5.1 SAGE I Aerosol Profiles Data Set This data set is written in HDF. FILE NAMING CONVENTION: sag1_aer_prf_yymm where yy represents the year and mm represents the month. VARIABLES: All records and parameters within this data set have been defined, including their minimum and maximum values in the HDF file. The read software will display these values. NOTES ON DATA: There are 34 monthly data files in this data set dating from February 1979 through November 1981. Every granule consists of 38 parameters per event/record. Users must take note that when ordering data within the IMS database, the longitude values are expected to be stored in the -180 to +180 degree format. This experiment stores the longitude values in 0 to 360 degree format within the data files. Please keep track of this! This pertains to the SAGE I AEROSOL PROFILES Data Set ONLY! INSTRUMENTATION: This information is provided in the User's Guides provided by the data producer. CONTACTS FOR DATA PRODUCTION INFORMATION: Dr. William P. Chu Atmospheric Science Division - Aerosol Research Branch 23A Langley Boulevard NASA Largely Research Center Hampton, Virginia 23681-2199 U.S.A. Phone: (757) 864-2675 FAX: (757) 864-3671 E-Mail: W.P.CHU@LaRC.NASA.GOV 6.0 Implementation Notes 6.1 HDF IMPLEMENTATION The read_sage1.c program is able to read SAGE I Aerosol Profiles, SAGE II Aerosol Profiles, SAGE II Ozone Profiles, SAGE II Nitrogen Dioxide Profiles, and SAGE II Water Vapor Profiles. When executed, the program prompts the user for the type of data it is expected to be reading. The program will then print out a list of the parameters that are included in each data set. All of the parameters the user selects will be printed out for every record/event. A description of these parameters are located in the User's Guide that is specific to each data set. Currently, users must contact Langley DAAC Users Services for copies of these guides (see section 1 for information on how to contact User Services). Along with these parameters, the program will print out additional information such as the Event Date, Event Time, Latitude, Longitude, Event Type (Sunrise or Sunset), and Minimum Altitude (this is the first value of the Geometric Altitude values for each record/event). The read program creates a report file with the name of the input data file with an extension of ".rpt." This report file is written to the current working directory. Once the user types the executable name at the command line, read_sage1, the user will see the following appear on the screen: command> read_sage1 ***************************************************** * * * SAGEs I & II HDF Read Program Version 7.0 * * * * * * This sample read program currently reads the * * following data sets: * * * * SAGE I Aerosol Profiles * * SAGE II Aerosol Profiles * * SAGE II Ozone Profiles * * SAGE II Nitrogen Dioxide Profiles * * SAGE II Water Vapor Profiles * * * * * * January 26, 1999 * ***************************************************** This is a list of all SAGE experiments. 1. SAGE I Aerosol Profiles 2. SAGE II Aerosol Profiles 3. SAGE II Ozone Profiles 4. SAGE II Nitrogen Dioxide Profiles 5. SAGE II Water Vapor Profiles Enter type of experiment (1 thru 5) ... 4 Enter the full data path as well as the data name. sag2_no2_prf_8410 In your output report file, do you want to include the file description? Enter 1 for yes and 2 for no .... 1 Would you like to have the program write out all of the parameters? Enter Y for yes or N for no. --> n Item Number Label 1 Event Date (yymmdd.0) 2 Event Time (hhmmss.0) 3 Subtangent Latitude 4 Subtangent Longitude 5 Event Type (1.0 = sunset) 6 Earth-Referenced Event Type (0.0 = sunrise 1.0 = sunset) 7 Spacecraft Beta Angle 8 Coded Time of Year (ddd.fract) 9 NMC Temperature 10 NMC Temperature Error 11 NMC Altitude 12 NMC Density 13 Air Density Error 14 NMC Temperature Correction for 5.0mb, 2.0mb, 1.0mb, and 0.4mb Level 15 Met array Model Data Pointer Please choose the numbers of the data items you wish to output. Enter -1 to continue to next list or 0 to begin processing. 1 -1 Item Number Label 16 Model Met Selection Code 17 LaRC Processing Date (yymmdd.0) 18 LaRC Processing Time (hhmmss.0) 19 Mean Subtangent Altitude of Event Limb Calibration 20 Scan Mirror Calibration Code Date 21 Quality Factor 453nm 22 Quality Factor 448nm 23 Latitude Corresponding to Altitude 24 Longitude Corresponding to Altitude 25 Time Span of Data from Level 1 through 70 26 Geometric Altitude 27 Corresponding Pressure 28 Corresponding Temperature 29 Number Density 30 Volumetric Mixing Ratio Please choose the numbers of the data items you wish to output. Enter -1 to continue to next list or 0 to begin processing. -1 Item Number Label 31 Number Density Error (% of value) 32 Volumetric Mixing Ratio Error (% of value) 33 Number Density Quality Bit Flag 34 Volumetric Mixing Ratio Quality Bit Flag Please choose the numbers of the data items you wish to output. Enter -1 to continue to next list or 0 to begin processing. 34 0 The following is a list of the parameters you have selected: 1 Event Date (yymmdd.0) 34 Volumetric Mixing Ratio Quality Bit Flag Would you like to make a new selection of these parameters or would you like this program to exit the selection process and begin retrieving the data? Enter Y for yes to retrieve data or N for no make a new selection. --> y Reading labels.... There are 115 records/number of events in the HDF file. NOTE: This will take some time to write out the report file. Reading data, Please wait ... ... and wait ... ... and wait ... @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ @ @ This program has completed and has created an output report @ @ file called sag2_no2_prf_8410.rpt in your current @ @ working directory. @ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Updated April 07, 1999 LD_008_020_001_00_00_0_19990407