|
||||||
|
|
||||||
This document describes the access software that is included on the CD-ROM version of the Historical Arctic Rawinsonde Archive (HARA). The purpose of this software is to familiarize the user with the structure of the CD-ROM and to provide examples of software routines that can be used to subset and extract the data residing on the HARA discs. Two versions of the access software are being supplied on the HARA discs; one was written using the C programming language, the other using FORTRAN. Where appropriate, the differences between the two versions will be noted. This software can be compiled on either a UNIX or Microsoft Disk Operating System (MS-DOS) platform. The software has been compiled and tested on an IBM PC using the both Microsoft (MS) C and FORTRAN compilers. To obtain assistance in using this software with other operating systems (e.g. VMS) contact NSIDC User Services.
1. Compiling the Source Code
1.1 Copy Source and Ancillary Files to Working Directory
1.1.1 UNIX Environment
1.1.2 MS-DOS Environment
1.2 Verify Mount Point for CD-ROM
1.2.1 UNIX Environment
1.2.2 MS-DOS Environment
1.3 Create the Executable File
1.3.1 UNIX Environment
1.3.2 MS-DOS Environment
2. Running the Program
2.1 Interactive Mode
2.1.1 Executing the Access Program
2.2 Non-interactive Mode
3. Format Description of the Data Extracted from the HARA CD-ROM
4. Description of Files Produced Using the HARA CD-ROM Access Software
5. Listing of Arctic WMO Stations
The first step in preparing to compile the HARA CD-ROM access software is to copy the source files from the CD-ROM to the directory where the executable is to be built. If the mount point for the HARA CD-ROM is "/CDROM" and the working directory is "/usr/people/mydir," then issue the following command replacing <PLATFORM> with UNIX or DOS and <language> with either C or FORTRAN.
cp /CDROM/software/<PLATFORM>/<language>/* /usr/people/mydir
Files required to compile and execute the C version of the software include:
Files required to compile and execute the FORTRAN version of the software include:
NOTE: Files copied from the CD-ROM to a local UNIX disk retain the 'read-only' attribute of the files residing on the CD-ROM. In order to modify or edit these files the attributes have to be changed to permit 'write' access. To change the file attributes, type in the following UNIX command:
#chmod u+w *
copy l:\software\<PLATFORM>\<language>\* d:\mydir\*
Files required to compile and execute the C version of the software include:
Files required to compile and execute the FORTRAN version of the software include:
After the source code files have been copied to a working directory verify that the "fpath" variable is defined correctly in the source file set1.c (set1.f for FORTRAN). This variable defines the path to the rawinsonde data located on the CD-ROM. The "openr()" function located in the set1 module was coded with a default value for "fpath." If the mount point is defined other than "/CDROM" then the value of "fpath" must be changed in the set1 source file.
In the C source file set1.c, the line
fpath[] = "/CDROM/data/19"
defines the value of the "fpath" variable.
In the FORTRAN source file, set1.f, the line
fpath = '/CDROM/data/19'//ext//"/"//idst(icnt)//'.'//ext
defines the value of the "fpath" variable.
If for some reason the mount point for the HARA CD-ROM cannot be defined as "/CDROM," then the set1 source file must be edited, replacing the text string "/CDROM" on the line defining the "path" variable with the text string defining the mount point for the HARA CD-ROM.
After the source code files have been copied to a working directory verify that the "fpath" variable is defined correctly in the source file set1.c (set1.f for FORTRAN). This variable defines the path to the rawinsonde data located on the CD-ROM. The "openr()" function located in the set1 module was coded with a default value for "fpath." If the mount point is defined other than "l:\" then the value of "fpath" must be changed in the set1 source file.
In the C source file set1.c, the line
fpath[] = "l:\\data\\19"
defines the value of the "fpath" variable.
In the FORTRAN source file, set1.f, the line
fpath = 'l:\data\19'//ext//"\"//idst(icnt)//'.'//ext
defines the value of the "fpath" variable.
If for some reason the mount point for the HARA CD-ROM cannot be defined as "l:\", then the set1 source file must be edited, replacing the text string "l:\" on the line defining the "fpath" variable with the text string defining the mount point for the HARA CD-ROM.
A makefile is included with the source files that were copied into the working directory (refer to 1.1 above). Rename the appropriate makefile (MakefileC or MakefileFOR) to "makefile." By issuing the command "make" at the shell prompt the source files will be compiled and linked into an executable file named "access."
There are multiple files containing subroutines that must be compiled and linked together. Refer to your compiler manual for exact instructions on how to accomplish this. The main program is named access.<c or for> with subroutines in files set0, set1, set2 ,(and global.c for C only).
The following command couples the required C-source modules using the MS C compiler and links the resulting object files creating the executable file, "ACCESS.EXE."
D:\>CL ACCESS.C SET0.C SET1.C SET2.C GLOBAL.C
Once the executable file has been created and the CD-ROM path has been verified the program should be ready to execute. There are two different modes in which the access program can be implemented. One is the interactive mode which requires the user to respond to a series of questions that request attributes, such as spatial and temporal ranges, to define the subset of data to be extracted from the CD-ROM. The other mode requires the user to prepare a text file containing the attributes of the subset to be extracted from the CD-ROM. An example of a file containing parameters that define a subset of HARA data to be transferred from CD-ROM to a working directory is included with the distribution (Section 2.2).
The access program should be run interactively until the user becomes familiar with the structure of the data set and the format of the output the program generates. The user is required to type in the responses to each query made by the access program before the program begins transferring data from the CD-ROM. The following table describes the parameters required as input to the access program.
Parameter Range --------------- ---------- WMO Station ID 00000-99999 Latitude 0-90 Longitude 0-360 Year 48 - 69 (Volume 1) 70 - 79 (Volume 2) 80 - 87 (Volume 3) Month 1-12 Hour 0-24 (GMT) Pressure Level 0-1200 (mb)
Note that the latitude and longitude of a station can vary slightly due to irregular station location changes.
To run either the C or FORTRAN version of the access program in the interactive mode simply type "access" at the shell prompt.
Example:
#access
This mode provides quicker and easier execution of the access program. In order to use this mode the user must prepare a file with all of the parameters that define the subset of the data on CD-ROM that is to be extracted. Samples of the parameter file (infile.dat) are included with the distribution. One of the sample files for the non-interactive mode is to be used with the FORTRAN version of the access program, the other with the C version.
2 !interaction mode (1 for batch 2 for interactive) 1 !request specification (1 for WMO 2 for lat-long) 72948 !station name(1 value) or lat-long range(4 values) 48 69 !year range (2 values) 1 12 !month range(2 values) 0 24 !hour range(2 values) 2 !mandatory level flag (1 for mandatory pressure levels else 2) 0 1200 !pressure range (2 values) 1 !output file flag (1 for multiple files 0 for 1 file)
2 !request specification (1 for WMO 2 for lat-long) 0 90 0 360 !station name(1 value) or lat-long range(4 values) 48 69 !year range (2 values) 1 12 !month range(2 values) 0 24 !hour range(2 values) 2 !mandatory level flag (1 for mandatory pressure levels else 2) 0 1200 !pressure range (2 values)
To execute the FORTRAN version of the access program in the non-interactive mode simply type "access" at the shell prompt. Observe that the parameter file must have the mode flag set to "1" for the access program to process the extraction request in the non-interactive mode.
To process the extraction request in the non-interactive mode using the C version of the access program enter "access" followed by the "-i" option followed by the name of the parameter filename at the shell prompt.
Example:
#access -i infile.dat
The data extracted from the HARA CD-ROM retains the same format as the data residing on the CD-ROM. The information for each sounding is comprised of a header and a series of measurements, each measurement taken at a particular pressure level. The format for each sounding can be described by the following FORTRAN format statements.
The format for the header record is:
FORMAT(A5,2I5,1X,4I2,1X,A3,I3,I5,I2,1X,I3,1X,I1)
while the format for each measurement in the sounding is:
FORMAT(2(a5,1X),14,1X,3(13,1X),4(A1,A1,1X),2A1).
A sample of the structure of a sounding follows:
Header: 72948 702023530 69 5 2 0 0 5 0 9 5 Sounding: 99999 99999 9999 999 999 999 9 9 9 9 9P 8500 1387 4 4 160 12 AP AP AP DP AP 7000 2929 -55 3 225 6 DP AP AP DP AP 5000 5489 -213 40 185 13 DP AP AP DP AP 500 99999 -549 999 999 999 9 AP 9 9 9P 440 99999 -507 999 999 999 9 9P 9 9 9P 320 99999 -531 999 999 999 9 9P 9 9 9P 300 99999 -523 999 999 999 9 CP 9 9 OP 230 99999 -503 999 999 999 9 9P 9 9 9P
For a complete description of the variables that correspond to HARA data formats refer to NSIDC Special Report 2 (1992), "The Historical Arctic Rawinsonde Archive Documentation Manual", section 4 or refer to the file FORMAT.DOC located in the DOCUMENT directory on the HARA CD-ROM.
The HARA CD-ROM access program produces the file "my_list.dat" each time the program executes. The file contains a list of the stations for which data are being extracted from the CDROM. This file is overwritten each time the access program is executed.
The default for presenting the data extracted from the HARA CD-ROM is to transfer the data into the file "outfile.dat" in the working directory. This file is overwritten each time the FORTRAN version of the access program is executed, whereas data are appended to this file each time the C version is executed. It is recommended that the file "outfile.dat" be renamed prior to or after each extraction process.
Besides the default for presenting the data extracted from the HARA CD-ROM, the user can specify the data be stored in multiple files. The access program partitions the extracted data into files containing only those soundings recorded for a single year that are associated with an individual station. For example, suppose the request was for an area that included five stations and the user is interested in retrieving only those soundings occurring between January and March for the years 1970 through 1974. Using the option to create multiple files, the results would be stored in 25 separate files (5 stations times 5 years = 25). The naming convention for files created using the multiple file option is to concatenate the WMO station identification number with the last two digits of the year and to append ".dat" as the file extension (e.g., 7002687.dat would contain sounding data recorded during 1987 at the station with the WMO identifier 70026).
To produce multiple files using the C version of the access program specify the "-o" option:
#access -i infile.dat -o
To produce multiple files using the FORTRAN version of the access program in the non-interactive mode set the parameter on the last line in the parameter file to 1 (section 2.3).
Care should be taken to ensure that there is sufficient disk space to accommodate the data extracted from the HARA CD-ROM.
A listing of the stations can be found in the stationwmo.dat file. An example of the contents of stationwmo.dat is listed below.
# WMO LAT LONG YR ID STATION NAME 1 71072 7623 24068 48 3 MOULD BAY, NT CANADA 2 71074 7868 25647 48 3 ISACHSEN, NT CANADA 3 71917 8000 27407 48 3 EUREKA, NT CANADA 4 71918 7303 27485 48 3 ARCTIC BAY, NT CANADA 5 71924 7472 26504 48 3 RESOLUTE BAY, NT CANADA 6 71938 6782 24487 48 3 COPPERMINE, NT CANADA 7 70026 7130 20322 48 4 BARROW, AK ALASKA 1 71072 7623 24068 49 3 MOULD BAY, NT CANADA 2 71074 7868 25647 49 3 ISACHSEN, NT CANADA 3 71917 8000 27407 49 3 EUREKA, NT CANADA 4 71924 7472 26504 49 3 RESOLUTE BAY, NT CANADA 5 71938 6782 24487 49 3 COPPERMINE, NT CANADA 6 70026 7130 20322 49 4 BARROW, AK ALASKA |
The column labeled # represents the number of the file associated with a single year and is used as a counter to track the number of stations contributing sounding data for a particular year. For example, the HARA disk contains rawinsondes measured from seven (7) stations during 1948.
For additional information or questions regarding the data or the access program contact NSIDC User Services:
NSIDC User Services
National Snow and Ice Data Center
CIRES, 449 UCB
University of Colorado
Boulder, CO 80309-0449 USA
phone: +1 303.492.6199
fax: +1 303.492.2468
form: Contact NSIDC User Services
e-mail: nsidc@nsidc.org
