1.1 Data Products and File Names. 4

DRAFT / SSAI

November 1, 2002

This is a work-in-progress document describing the access of level 0, level 1, and level 2 data from the Microwave Limb Sounder (MLS) instrument, which is part of a complement of instruments on the Upper Atmosphere Research Satellite (UARS). MLS primarily measures temperature and composition of important minor constituents of the earth’s stratosphere. Originally, the data were (are) generated for computer systems compatible with the Compaq (Digital Equipment Corporation) Computer Corporation VAX/Alpha computers running under the VMS operating system. The following describes those data that are converted to be compatible with Silicon Graphics Incorporated (SGI) computer systems running under IRIX. Therefore they are also compatible with the facilities of the GSFC Distributed Active Archive Center (DAAC). The following also describes software for the access of the converted data files.

1 DRAFT / SSAI

1.0 Introduction...... 4 1.1 Data Products and File Names...... 4 1.1.1 Level 0 Data Products and File Names...... 4 1.1.2 Level 1 Data Products and File Names...... 5 1.1.3 Level 2 Data Products...... 5 1.2 Software Products and File Names...... 5 1.2.1. Level 0 Software...... 6 1.2.2 Level 1 Software...... 6 1.2.3 Level 2 Software...... 7 1.3 Additional Software...... 7 1.3.1 Additional level 0 Software...... 7 1.3.2 Additional Level 1 software...... 7 1.3.3 Additional Level 2 software...... 8 2.0 Related Documentation...... 8 3.0 MLS Files and Data Structures...... 9 3.1 Level 0 Files and Data Structures...... 9 3.2 Level 1 File and Data Structure...... 10 3.3 Level 2 File and Data Structure...... 10 4.0 Access Software...... 11 4.1 General Considerations...... 11 4.1.1 Arrays...... 11 4.1.2 Fill Data...... 11 4.1.3 Logical Variables...... 11 4.2 Level 0 Fortran Software...... 12 4.2.1 Fortran Access Routine to Read Level 0 Data (fth_readl0)...... 12 4.3 Level 0 C Software...... 13 4.3.1 C Function Routine to Read Level 0 Data (mcb_readl0_c)...... 13 4.4 Level 1 Fortran Software...... 14 4.4.1 Level 1 Fortran Access Routine for Header Records(fth_read_mls_l1_header_str)...... 14 4.4.2 Level 1 Fortran Access Routine for Data Records (fth_read_mls_l1_mlsrad_str)...... 18 Routine fth_read_mls_l1_mlsrad_str (file fth_read_mls_l1_mlsrad_str.for) reads the data records of the MLS level 1 file of subtype mlsrad. Access is direct. The first data record is record number 4 of the file...... 18 4.5 Level 1 C Software...... 21 4.5.1 Level 1 C Header Record Access Function Routine (fth_rd_mls_l1_hdr_str_c)...... 21 The C function fth_rd_mls_l1_hdr_str_c (file fth_rd_mls_l1_hdr_str_c.c) reads the 3 MLS level 1 header (subtype MLSRAD). The MLS level 1 data file consists of fixed length records. The first 3 are header records...... 21 4.5.2 Level 1 C Data Record Access Function Routine (fth_rd_mls_l1_str_c)...... 22 Function fth_rd_mls_l1_str_c (file fth_rd_mls_l1_str_c.c) reads the data records of the MLS level 1 file of subtype mlsrad. Access is direct. The first data record is record number 4...... 22 4.5.3 Level 1 C Access Array Transform Routines...... 23 4.6 Level 2 Fortran Software...... 23 4.6.1 Level 2 Fortran File Header Access Routine (fth_mls_l2_l2out_str)...... 23 4.7 Level 2 C Software...... 24 4.7.1 Level 2 C File Header Access Routine (fth_read_mls_l2_str_c)...... 24 Appendix: Additional Software...... 26 A.1 Additional Level 0 Fortran Software...... 26 A.1.1 Level 0 Fortran File Open Routine (opn_l0_file)...... 26 A.1.2 Level 0 Fortran File Name Routine (gen_l0_name)...... 27 A.1.3 Level 0 Sample Fortran Driver and Link Procedure...... 28

2 DRAFT / SSAI

A.2 Additional Level 0 C Software...... 29 A.2.1 Level 0 C File Open Function Routine (opn_l0_file_c)...... 29 A.2.2 Level 0 C File Name Function Routine (gen_l0_name_c)...... 30 A.2.3 Level 0 Sample C Driver and Link Procedure...... 30 A.3 Additional Level 1 Fortran Software...... 31 A.3.1 Level 1 Fortran File Open Routine (opn_l1_file)...... 31 A.3.2 Level 1 Fortran File Name Routine (gen_l1_name)...... 33 A.3.3 Level 1 Sample Fortran Driver and Link Procedure...... 33 A.4 Additional Level 1 C Software...... 34 A.4.1 Level 1 C File Open Function (opn_l1_file_c)...... 35 A.4.2 Level 1 C File Name Function (gen_l1_name_c)...... 35 A.4.3 Level 1 Sample C Driver and Link Procedure...... 36 A.5 Additional Level 2 Fortran Software...... 37 A.5.1 Level 2 Fortran File Open Routine(opn_l2_file)...... 37 A.5.2 Level 2 Fortran File Name Routine (gen_l2_name)...... 38 A.5.3 Level 2 Sample Fortran Driver and Link Procedure...... 38 A.6 Additional Level 2 C Software...... 40 A.6.1 Level 2 C File Open Code (opn_l2_file_c)...... 40 A.6.2 Level 2 C File Name Function (gen_l2_name_c)...... 41 A.6.3 Level 2 Sample C Driver and Link Procedure...... 41

3 DRAFT / SSAI

1.0 Introduction.

This document describes the access of level 0, level 1, and level 2 data from the Microwave Limb Sounder (MLS) instrument, which is part of a complement of instruments on the Upper Atmosphere Research Satellite (UARS). MLS primarily measures important minor constituents and temperature in the earth’s stratosphere and mesosphere. Currently, this document applies to CLAES level 0, level 1, and level 2 data files that have been converted to be compatible with Silicon Graphics computers running under IRIX. The converted files are therefore also compatible with the facilities of the NASA GSFC Distributed Active Archive Center (DAAC) facilities. The original files were created by UARS production processing running under the Compaq (Digital Equipment Corporation (DEC)) VMS operating system, on the UARS Central Data Handling Facility (CDHF). Corresponding activities for the UARS instrument calibration data will be included at a later date. The conversion of UARS level 3 data is not part of this activity.

The software that does the actual conversion of the original files is also not part of this description. The following describes the converted files and the software that are provided to access the converted files. Routines to read the converted file are provided in both Fortran and C. The original data were produced using Fortran code.

1.1 Data Products and File Names.

Data products consist of the various levels of MLS data. Basically, the level 0 data are the telemetry data that have been sorted and stored. Level 1 data include calibrated data in engineering units, such as radiances, while level 2 data are the products used for scientific analysis, such as composition and temperature. The data files within a data level may be further divided into subtypes, such as the specific parameter(s) measured. As described in more detail below, file names are based on the data level, on the data type (subtype), and on the day of year, among other things. Examples of subtypes are ozone mixing ratios and radiances.

1.1.1 Level 0 Data Products and File Names

There are 15 types of UARS level 0 files, nominally one for each day. Of these, 5 files are pertinent to MLS. Examples are

mls_l0_0120.v0002_c01_prod engineering_l0_d1101.v0002_c01_prod spacecraft_l0_d2373.v0002_c01_prod obc_l0_d1673.v0002_c01_prod quality_l0_d1644.v0002_c01_prod;1

The UARS level 0 file name convention begins with the type acronym (e.g., mls, engineering,...), followed by the level(0). Next is the UARS day number(e.g.,0120; September 12, 1991 corresponds to UARS day number 1, January 19 1992 is UARS day 130). This is followed by the

4 DRAFT / SSAI data version number(0002), and then by the cycle number(01). The data version number corresponds to the software that produces the data, and the data cycle number is determined by the UARS level 0 processing. For each data version, there is a cycle number that is nominally 1. If reprocessing is needed for the same version, the cycle is incremented. The most recent data correspond to the largest version and cycle numbers. The last four characters of the file name are always 'prod'.

In the above, file mls_l0_d0120.v0002_c01_prod is the MLS level 0 data for UARS day 120, while the other 4 types of files contain complementary flight data.

1.1.2 Level 1 Data Products and File Names

There is one type of MLS level 1 (subtype mlsrad) data file which is converted and archived. Nominally, the original files are generated on a daily basis and there is one file for each day. A typical file name of a converted file is

mls_l1_smlsrad_d0120.v0004_c01_bnbe

The UARS file name convention begins with the instrument acronym (MLS), followed by the level (1), which in turn is followed by the subtype (mlsrad). Next is the UARS day number (e.g., September 12, 1991 corresponds to UARS day number 1, and January 1 1992 is UARS day 112) and the data version number (0004), followed by the cycle number (01). The last four characters are 'prod' as originally generated on the UARS CDHF, but have been replaced here by 'bnbe' to denote that the files have been converted.

1.1.3 Level 2 Data Products

As in the level 1 case, there is one type of MLS level 2 data (subtype L2OUT) file that is converted and archived. Nominally the files are generated on a daily basis and there is one file for each day. A typical file name is

mls_l2_sl2out_d0110.v0004_c01_prod

The file name convention is similar to that for level 1 files, described above.

1.2 Software Products and File Names

The software products are divided into required software and additional products. The required software consists of access functions/routines in both Fortran and C, and which can be used to read the files. Additional software are those which are provided as a convenience for the user and is not formally part of this software package. Examples of additional software are sample drivers that use the required software, and routines that generate the proper file names and open the files. Additional software are described in the Appendix.

5 DRAFT / SSAI

Because some of the software are made to run under both IRIX and under VMS, for the sake of consistency, the following file name conventions are used for the software. Files names for Fortran code end in '.for', and files written in C will end in '.c'. Link scripts and executable names end in '.com' and '.exe', respectively.

The names of the software modules are listed next.

1.2.1. Level 0 Software

The following routine/function can be used to read each of the 5 level 0 files listed above. File names are given in parenthesis.

Routine name Description (file name) ------fth_readl0 Fortran routine to read level 0 files (fth_readl0.for) of all types mcb_readl0_c C code to read level 0 files of all (mcb_readlo_c.c) types

1.2.2 Level 1 Software

Software is provided to read header and data records for the files given above.

Routine name Description (file name) ------fth_read_mls_l1_header_str Fortran routine to read the 3 level 1 (fth_read_mls_l1_header_str.for) header records fth_read_mls_l1_mlsrad_str.for Fortran routine to read level 1 data (fth_read_mls_l1_mlsrad_str.for) records fth_rd_mls_l1_hdr_str_c C code to read the 3 level 1 header (fth_rd_mls_l1_hdr_str_c.c) records fth_rd_mls_l1_str_c C code to read the level 1 data (fth_rd_mls_l1_str_c.c) records.

The following C code are also required to transform multidimensional arrays such that C and Fortran software present the arrays in the same manner (row major). However, users need not be concerned with their usage, as they are called only by the read software provided.

Users need only link the following C functions

for_c_mtrx_2 (for_c_mtrx_2.c) ch_for_c_mtrx_2 (ch_for_c_mtrx_2.c)

6 DRAFT / SSAI

int2_for_c_mtrx_3 (int2_for_c_mtrx_3.c)

The corresponding file names are in parenthesis)

1.2.3 Level 2 Software

Module name Description ------fth_mls_l2_l2out_str Fortran routine to read level 2 header and data records of subtype L2OUT fth_read_mls_l2_str_c.c C function to read level 2 header and data records of subtype L2OUT

1.3 Additional Software

As noted earlier, additional software are provided as a convenience to users, but is not formally part of the software package per se. Used together with the access routines, they can be linked into executables to read and list the data. Here, they are listed for completeness. Details are given in the Appendix. File names are given in parenthesis.

1.3.1 Additional level 0 Software

Routine Name Description (file name) ------get_l0 Fortran sample driver for using level 0 (get_l0.for) routines opn_l0_file Fortran code to open level 0 files (opn_l0_file.for) gen_l0_name Fortran code to generate level 0 file names (gen_l0_name.for) get_l0_c C sample driver for using level 0 (get_l0_c.c) function routines opn_l0_file_c C code to open level 0 files (opn_l0_file_c.c) gen_l0_name_c C code to generate level 0 file names (gen_l0_name_c.c)

1.3.2 Additional Level 1 software

Routine name Description (file name) get_mls_l1_mlsrad_str sample Fortran driver to use

7 DRAFT / SSAI

(get_mls_l1_mlsrad_str.for) provided read routines opn_l1_file Fortran routine to open level 1 (opn_l1_file.for) files gen_l1_name Fortran routine to generates level 1 (gen_l1_name.for) file names for a specific day and data version get_mls_l1_mlsrad_str_c sample C driver which can be used (get_mls_l1_mlsrad_str_c.c) with the read routines opn_l1_file_c c code to open level 1 files (opn_l1_file_c.c) gen_l1_name_c c code to generate level 1 file (gen_l1_name_c.c) names

1.3.3 Additional Level 2 software

Routine name Description (file name) ------opn_l2_file Fortran routine to open level 2 files (opn_l2_file.for) gen_l2_name Fortran routine to generate level 2 file (gen_l2_name.for) names get_mls_l2_l2out_str Fortran sample driver which uses above (get_mls_l2_l2out_str.for) software opn_l2_file_c c code to open level 2 files (opn_l2_file_c.c) gen_l2_name_c c code to generate level 2 file names (gen_l2_name_c.c) get_mls_l2_l2out_str_c c sample driver which uses above software (get_mls_l2_l2out_str_c.c)

2.0 Related Documentation

A general description of the scientific goals and the instrument is found in the following paper:

Barath, F. T.,M.C. Chavez, R. E. Cofield, D. A. Flower, M. A. Frerking, M. B. Gram, W. M. Harris, J. R. Holden, R. F. Jarnot, W. G. Kloezeman, G. J. Klose, G. K. Lau, M. S. Loo, B. J. Maddison, R. J. Mattauch, R. P. McKinney, G. E. Peckham, H. M. Pickett, G. Siebes, F. S. Soltis, R. A. Suttie, J. A. Tarsala, J. W. Waters, and W. J. Wilson, The Upper Atmosphere Research Satellite Microwave Limb Sounder Instrument, J. Geophys. Res., 98, 10,751-10,762, June 20, 1993.

8 DRAFT / SSAI

Related MLS documents are a) UPPER ATMOSPHERE RESEARCH SATELLITE MICROWAVE LIMB SOUNDER PRODUCTION SOFTWARE USERS GUIDE VERSION 4.11 DECEMBER,18 1992

This document is contained in file mls_user_guide_94nov30.doc. b) UPPER ATMOSPHERE RESEARCH SATELLITE MICROWAVE LIMB SOUNDER Standard Formatted Data Units File Class Document for MLS Level 2 Data File

This document is contained in file nursml01.doc. c) UPPER ATMOSPHERE RESEARCH SATELLITE MICROWAVE LIMB SOUNDER Standard Formatted Data Units Whole Data Set Document

This document is contained in file nursml02.doc d) UARS CDHF SOFTWARE SYSTEM (UCSS) PROGRAMMER'S GUIDE TO PRODUCTION SOFTWARE SUPPORT SERVICES, COMPUTER SCIENCES CORPORATION, FEBRUARY,1993.

This document describes access routines for UARS data levels 0 and 3, but not for levels 1 and 2. However, there is still general information that may be useful to users. This document can be obtained from the UARS Program Assistance Center (PAC).

There is unofficial documentation available for the MLS level 1 data in file

mls_1to3.doc

3.0 MLS Files and Data Structures

3.1 Level 0 Files and Data Structures

Unlike the converted level 1 and level 2 files, the level 0 files are unchanged from their original VMS versions. The contents of level 0 files are mostly byte-oriented, and the relatively few data words that need to be converted are done so by the read routine that is provided and described below. Consequently, users should only use the included software for this purpose.

All Level 0 files contain fixed length records, and record access is direct. The record lengths for relevant file types are as follows

TYPE RECORD LENGTH (BYTES) ------mls 10304 engineering 8256 spacecraft 21568 obc 14400 quality 2532

For more details, refer to the document

9 DRAFT / SSAI

UARS CDHF SOFTWARE SYSTEM (UCSS) PROGRAMMER'S GUIDE TO PRODUCTION SOFTWARE SUPPORT SERVICES, COMPUTER SCIENCES CORPORATION,OCTOBER,1995.

The contents can be found in file

ucss_pg_oct95.mem

3.2 Level 1 File and Data Structure

An example of a converted level 1 MLS file is the Limb Radiance File

mls_l1_smlsrad_d0120.v0004_c01_bnbe

The file name convention is described above in Section 1.1.2.

This data file of subtype MLSRAD is the primary Level 1 product and is passed to the Level 2 MLS production-processing programs. It is made up of 3 header records, followed by numerous data records. The header records contain information that uniquely identifies the file and the data within. The data records contain calibrated radiances, orbit, attitude, and ephemeris data, along with other information concerning the instrument. The files consist of fixed length records written in binary. All files have the same record length that is 3584 words (four bytes per word). Data in the converted files appear in the same order and the same records as in the original VMS files, and direct access in reading the records can be used.

Examples of other types of catalogued level 1 MLS files are

mls_l1_smlseng_d0120.v0004_c01_prod mls_l1_slog_d0120.v0001_c01_prod mls_l1_smlsdiag_d0120.v0004_c01_prod

However, these types are not needed for archival purposes.

Currently, there is no available documentation on the level 1 data per se.

3.3 Level 2 File and Data Structure

Examples of level 2 files are

mls_l2_sl2out_d0110.v0004_c01_prod mls_l2_smls_lmfq_d0110.v0004_c01_prod

The level 2 file with subtype l2out contains the MLS retrieved data, among other parameters. The files consist of fixed length records that are 3456 words (a word is 4 bytes long). Data in the converted files appear in the same order and the same records as in the original VMS files. Direct access can be used.

The level 2 data with subtype MLS_LMFQ (in the file name) does not need to be converted and archived.

10 DRAFT / SSAI

Documentation for level 2 data is contained in file nursml01.doc

4.0 Access Software

Software for accessing the data is provided in the form of Fortran routines and C functions. For consistency, because software is provided in both Fortran and C, and because some of the software are made to run under both IRIX and under VMS, the following name conventions are used for the software: a) file names for Fortran code end in '.for', and files written in C end in '.c'; b) link scripts and executable file names end in '.com' and '.exe', respectively.

4.1 General Considerations.

The converted files contain the same records and structures as the original files. Because the order and structure of the records have been preserved, the original MLS documentation remain applicable, but with the following issues in this section borne in mind.

4.1.1 Arrays

The indices of arrays that are read by Fortran routines begin with the same values as the original VMS routines. Arrays that are read by C programs always begin with index 0.

For multidimensional arrays, C and Fortran are different as to which index varies fastest (i.e., row major, row minor). The C access routines that are provided account for this, so that the various indices of the arrays have the same meaning for both C and Fortran routines, and conform to the original documentation.

4.1.2 Fill Data.

Nominally, the original VMS files use an 'illegal floating point' number for fill data. This number in HEX is '8000'X. MLS does not use the illegal floating point for fill data, so the user need not take preventive measures to avoid unexpected aborts.

4.1.3 Logical Variables

The original VMS data used the value -1 for logical variables to denote true. In agreement with MLS personnel, the values of -1 are changed to + 1 in the converted files.

11 DRAFT / SSAI

4.2 Level 0 Fortran Software

4.2.1 Fortran Access Routine to Read Level 0 Data (fth_readl0)

Because the level 0 data files are unchanged from the original VMS versions, users should use only fth_readl0 (file fth_readl0.for), or its C equivalent, for reading the level 0 data on systems which conform to the big endian addressing convention (e.g., SGI, SUN). The level 0 data files are essentially byte-oriented, and only the first 64 bytes of the data records (the data record header) need be converted. It was judged that this conversion should be done by the read routine. Record access is direct, and record 1 is the file label record (all ASCII) followed by data records. The first 64 bytes of each data record (the data record header) are mostly information in integer words, and is converted by the read software. The rest of each data record is byte- oriented.

Usage:

CALL FTH_READL0(LUN_RD,IREC,IREC_LEN,L0_BUFF, & ISWAP,IOS_RD)

ARGUMENT DESCRIPTION

ARGUMENT TYPE I/O DESCRIPTION ------LUN_RD I*4 I LOGICAL UNIT OF INPUT FILE IREC I*4 I RECORD TO READ (1 OR GREATER) IREC_LEN I*4 I RECORD LENGTH IN BYTES claes 24640 haloe 16448 hrdi 19520 isams 8256 mls 10304 pem 28736 solstice 2532 susima 8256 susimb 8256 windii 16448 acrim 4160 engineering 8256 spacecraft 21568 obc 14400 quality 2532 L0_BUFF CHAR*1 O BUFFER CONTAINING LEVEL 0 DATA (IREC_LEN) ISWAP I*4 I 0:FOR LITTLE ENDIAN COMPUTERS 1:FOR BIG ENDIAN COMPUTERS IOS_RD I*4 O READ STATUS 0:NO ERROR

This routine calls 3 other routines that are used to convert from little endian to big endian standards, namely,

swap32 (swap32.for) swap16 (swap16.for) swap64 (swap64.for)

12 DRAFT / SSAI

The file names are in parenthesis). Users need not know how to call these routines explicitly as they are used only by fth_readl0.

4.3 Level 0 C Software

4.3.1 C Function Routine to Read Level 0 Data (mcb_readl0_c)

Because the level 0 data files are unchanged from the original VMS versions, users should use only mcb_readl0_c (file mcb_readl0_c.c), or its Fortran equivalent, for reading the level 0 data on systems which conform to the big endian addressing convention (e.g., SGI, SUN).

Usage: void mcb_readl0_c(FILE *fp_rd,int irec,int in_recl_byte, signed char *l0_buff,int iswap,int *ios_rd);

mcb_readl0_c(fp_rd,irec,in_recl_byte,&l0_buff[0],iswap,&ios_rd);

/* ------THIS ROUTINE READS THE UARS LEVEL 0 DATA. IT ASSUMES THAT THE DATA FILE CORRESPONDS TO THE ORIGINAL, VMS DATA FILES. IN ORDER TO INTERPRET CORRECTLY, FOR BIG ENDIAN COMPUTERS, ISWAP SHOULD BE SET TO 1.

------

ARGUMENT TYPE I/O DESCRIPTION ------fp_rd FILE* I pointer to input file-buffer-string irec I*4 I RECORD NUMBER TO READ (1 OR GREATER) irec_len I*4 I RECORD LENGTH IN BYTES l0_buff CHAR*1 O BUFFER CONTAINING LEVEL 0 DATA iswap I*4 I 0:FOR LITTLE ENDIAN COMPUTERS 1:FOR BIG ENDIAN COMPUTERS ios_rd I*4 O READ STATUS 0:NO ERROR ------

This routine calls 3 other routines that are used to convert from little endian to big endian standards, namely,

swap32_c (swap32_c.c) swap16_c (swap16_c.c) swap64_c (swap64_c.c)

Users need not know how to invoke these routines explicitly as they are used only by mcb_readl0_c.

13 DRAFT / SSAI

The software consists of one routine which users can use to read the 3 level 1 header records and 1 routine which users can use to read the data records. The records are accessed using direct access. The header records are numbered 1,2,3 respectively, and the data record access routine is called with input record number 4 and higher.

Additional software in the form of a sample driver, a file name generation routine, and a file open routine are provided. A procedure is also provided to link the driver and routines. The resulting executable can be used to read the data and write selected portions to an output file for analysis or plots. Details are given in the Appendix.

4.4.1 Level 1 Fortran Access Routine for Header Records(fth_read_mls_l1_header_str)

Routine fth_read_mls_l1_header_str (file fth_read_mls_l1_header_str.for) reads the 3 header records of the MLS level 1 file of subtype mlsrad.

Usage:

CALL FTH_READ_MLS_L1_HEADER_STR(LUN_RD,IREC, & HEADER,UIP,IOS)

ARGUMENT TYPE I/O DESCRIPTION ------LUN_RD I*4 I LOGICAL UNIT NUMBER OF READ FILE IREC I*4 I RECORD NUMBER TO BE READ (1,2,3) HEADER RECORD O HEADER RECORD, FRONT END UIP RECORD O USER INPUT INFORMATION, PART OF FILE RECORD. IF RECORD IS 1 RECORD UIP.PART1 IS READ OF FILE RECORD. IF RECORD IS 2 RECORD UIP.PART2 IS READ OF FILE RECORD. IF RECORD IS 3 RECORD UIP.PART3 IS READ IOS I*4 O FORTRAN READ STATUS

The record HEADER has the following structure: structure /lvl1_hdr_rec/ ! Size (in Bytes)

character*1 TYPE ! 1 character*1 QUALIFIER ! 1 byte qualifier_pad ! 1 character*1 FILE_TYPE ! 1 integer*4 RECORDNO ! 4

14 DRAFT / SSAI

integer*4 WRITE_TIME(2) ! 8 character*4 LVL1_VERSIONNO ! 4 integer*4 NUMMMAF ! 4 integer*4 UARS_DAY ! 4 integer*4 START_TIME(2) ! 8 integer*4 STOP_TIME(2) ! 8 integer*4 MLS_STATUS_DAY ! 4

end structure ! 48 Bytes

The record UIP is based on the following structures: structure /ptg_fov_table_rec/ integer*4 ENCR ! 4 real*4 AZIM ! 4 real*4 ELEV ! 4 end structure ! Total: 12 structure /lvl1_uip1_rec/

* begin list 1 size of variable

real*4 ANT_RAD_OFFSET(3) ! 12 real*4 ANT_XMISSION(3) ! 12 character*12 ATT_TYP_VER ! 12 logical*1 BAD_CHANNEL_L1(ncmax, 2) ! 180 real*4 CAL_RADIANCE_RNG(2) ! 8 character*3 CAL_REF ! 3 byte cal_ref_pad ! 1 character*3 CAL_TYPE ! 3 byte cal_type_pad ! 1 integer*4 CONSTRAINT_ORDER ! 4 real*4 FC(ncmax,2) ! 720 character*80 FILE_COMMENT ! 80 real*4 GAIN_RNG(2) ! 8 real*4 HGA_INTERFER_RNG(2,40) ! 320 integer*4 HGA_INTERFER_RNG_NUM ! 4

end structure ! Total size: 1368 bytes

structure /lvl1_uip2_rec/

integer*4 MAFA ! 4 real*4 MIN_FIT_SIGMA ! 4 integer*4 MIN_GAIN_PTS ! 4 real*4 MU(ncmax,2) ! 720 real*4 OBJECT_FOV ! 4 real*4 OBJECT_SPV ! 4 character*12 ORB_TYP_VER ! 12 character*1 OVERRIDE(ifc_max) ! 32 real*4 PTG_FOV_AZIM_REF(2) ! 8

15 DRAFT / SSAI

real*4 PTG_FOV_AZIM_WDTH ! 4 integer*4 PTG_FOV_BO_MAP(7) ! 28 integer*4 PTG_FOV_BO_NUM ! 4 real*4 PTG_FOV_ELEV_REF(2) ! 8 real*4 PTG_FOV_ELEV_WDTH ! 4 record /ptg_fov_table_rec/ PTG_FOV_TABLE(5) ! 60 real*4 PTG_INST2MACS_ELEV_ERR ! 4 real*4 PTG_SPV_AZIM ! 4 real*4 PTG_SPV_AZIM_WDTH ! 4 integer*4 PTG_SPV_BO_MAP(7) ! 28 integer*4 PTG_SPV_BO_NUM ! 4 real*4 PTG_SPV_ELEV ! 4 real*4 PTG_SPV_ELEV_WDTH ! 4 character*1 QUALIFIER ! 1 byte qualifier_pad(3) ! 3

structure /lvl1_uip3_rec/

***** * begin list 3 size of variable

real*4 REC_NOISE_RNG(2,ncmax) ! 720 integer*4 REF_MMIF ! 4 integer*4 REJECT_LK_AHEAD ! 4 real*4 STD_SPV_RNG(2) ! 8 real*4 STD_TAR_RNG(2) ! 8 real*4 STD_ZER_RNG(2) ! 8 real*4 S_TEMP ! 4 real*4 THEORETIC_ZERO_VAR ! 4 real*4 THERMAL_H_MATRIX(2,16) ! 128 real*4 TRANS_INST2OBS(3,3) ! 36 real*4 TRANS_OBS2MACS(3,3) ! 36 integer*2 WD_100_MASK(2) ! 4 logical*1 WD_101_QUAL(ifc_max) ! 32 integer*2 WD_102_MASK(2) ! 4 logical*1 WD_103_QUAL(ifc_max) ! 32 logical*1 WD_104_QUAL(ifc_max) ! 32 logical*1 WD_96_QUAL(ifc_max) ! 32 logical*1 WD_98_QUAL(ifc_max) ! 32 logical*1 WD_99_QUAL(ifc_max) ! 32 integer*4 WINDOW_SZ ! 4

The record UIP follows the following structure: structure /lvl1_uip_rec/

union map ! element structure

16 DRAFT / SSAI

real*4 ANT_RAD_OFFSET(3) ! 12 real*4 ANT_XMISSION(3) ! 12 character*12 ATT_TYP_VER ! 12 logical*1 BAD_CHANNEL_L1(ncmax, 2) ! 180 real*4 CAL_RADIANCE_RNG(2) ! 8 character*3 CAL_REF ! 3 byte cal_ref_pad ! 1 character*3 CAL_TYPE ! 3 byte cal_type_pad ! 1 integer*4 CONSTRAINT_ORDER ! 4 real*4 FC(ncmax,2) ! 720 character*80 FILE_COMMENT ! 80 real*4 GAIN_RNG(2) ! 8 real*4 HGA_INTERFER_RNG(2,40) ! 320 integer*4 HGA_INTERFER_RNG_NUM ! 4

* end list 1 Total size: 1368 bytes

end map map ! record structure record /lvl1_uip1_rec/ PART1 ! 1368 bytes end map end union ------union map ! element structure ***** * begin list 2 size of variable

integer*4 MAFA ! 4 real*4 MIN_FIT_SIGMA ! 4 integer*4 MIN_GAIN_PTS ! 4 real*4 MU(ncmax,2) ! 720 real*4 OBJECT_FOV ! 4 real*4 OBJECT_SPV ! 4 character*12 ORB_TYP_VER ! 12 character*1 OVERRIDE(ifc_max) ! 32 real*4 PTG_FOV_AZIM_REF(2) ! 8 real*4 PTG_FOV_AZIM_WDTH ! 4 integer*4 PTG_FOV_BO_MAP(7) ! 28 integer*4 PTG_FOV_BO_NUM ! 4 real*4 PTG_FOV_ELEV_REF(2) ! 8 real*4 PTG_FOV_ELEV_WDTH ! 4 record /ptg_fov_table_rec/ PTG_FOV_TABLE(5) ! 60 real*4 PTG_INST2MACS_ELEV_ERR ! 4 real*4 PTG_SPV_AZIM ! 4 real*4 PTG_SPV_AZIM_WDTH ! 4 integer*4 PTG_SPV_BO_MAP(7) ! 28 integer*4 PTG_SPV_BO_NUM ! 4 real*4 PTG_SPV_ELEV ! 4 real*4 PTG_SPV_ELEV_WDTH ! 4 character*1 QUALIFIER ! 1 byte qualifier_pad(3) ! 3

17 DRAFT / SSAI

***** end map map ! record structure record /lvl1_uip2_rec/ PART2 ! 956 bytes end map end union !------union map ! element structure

real*4 REC_NOISE_RNG(2,ncmax) ! 720 integer*4 REF_MMIF ! 4 integer*4 REJECT_LK_AHEAD ! 4 real*4 STD_SPV_RNG(2) ! 8 real*4 STD_TAR_RNG(2) ! 8 real*4 STD_ZER_RNG(2) ! 8 real*4 S_TEMP ! 4 real*4 THEORETIC_ZERO_VAR ! 4 real*4 THERMAL_H_MATRIX(2,16) ! 128 real*4 TRANS_INST2OBS(3,3) ! 36 real*4 TRANS_OBS2MACS(3,3) ! 36 integer*2 WD_100_MASK(2) ! 4 logical*1 WD_101_QUAL(ifc_max) ! 32 integer*2 WD_102_MASK(2) ! 4 logical*1 WD_103_QUAL(ifc_max) ! 32 logical*1 WD_104_QUAL(ifc_max) ! 32 logical*1 WD_96_QUAL(ifc_max) ! 32 logical*1 WD_98_QUAL(ifc_max) ! 32 logical*1 WD_99_QUAL(ifc_max) ! 32 integer*4 WINDOW_SZ ! 4

end map map ! record structure record /lvl1_uip3_rec/ PART3 ! 1164 bytes end map end union

end structure ! Total bytes: 3488

The record definitions are:

record /lvl1_hdr_rec/ header record /lvl1_uip_rec/ uip

18 DRAFT / SSAI

4.4.2 Level 1 Fortran Access Routine for Data Records (fth_read_mls_l1_mlsrad_str)

Routine fth_read_mls_l1_mlsrad_str (file fth_read_mls_l1_mlsrad_str.for) reads the data records of the MLS level 1 file of subtype mlsrad. Access is direct. The first data record is record number 4 of the file.

Usage:

CALL FTH_READ_MLS_L1_MLSRAD_STR(LUN_RD,IREC,LVL1_RAD,IOS)

ARGUMENT LIST DESCRIPTION

ARGUMENT TYPE I/O DESCRIPTION ------LUN_RD I*4 I LOGICAL UNIT NUMBER OF INPUT FILE IREC I*4 I RECORD NUMBER TO READ LVL1_RAD RECORD O OUTPUT RECORD IOS I*4 O FORTRAN READ STATUS (0:NO ERROR)

The record LVL1_RAD is based on the following structures:

structure /oa_buffer_rec/

logical*1 PTG_FOV_BO_DIAG_MAP(7) ! 7 byte ptg_fov_pad ! 1

character*12 OA_ATT_RETRN ! 12 character*12 OA_ORB_RETRN ! 12

integer*4 OA_EPHEM_STATUS ! 4 integer*4 OA_LIMB_CALC_STATUS(ifc_max) ! 128 integer*4 OA_SAT_ATT_STATUS(ifc_max) ! 128 integer*4 OA_SAT_ORB_STATUS(ifc_max) ! 128 integer*4 PTG_FOV_BO_DIAG_MMIF_FST ! 4 integer*4 PTG_FOV_BO_DIAG_MMIF_LST ! 4 integer*4 PTG_FOV_BO_DIAG_MMIF_NUM ! 4 integer*4 REF_MMIF ! 4 integer*4 REF_SOLAR_ILLUM ! 4 integer*4 REF_TIME(2) ! 8 integer*4 SAT_GEOD_STATUS ! 4

real*4 EARTH_GEOD_RAD(ifc_max) ! 128 real*4 GRNW_SID_TIME ! 4 real*4 PTG_FOV_AZIM_OFFSET(ifc_max) ! 128 real*4 PTG_FOV_AZIM_THM(2) ! 8 real*4 PTG_FOV_BO_DIAG_AZIMDIF ! 4 real*4 PTG_FOV_BO_DIAG_ELEVDIF ! 4 real*4 PTG_FOV_BO_DIAG_MMAF(7) ! 28 real*4 PTG_FOV_ELEV_OFFSET(ifc_max) ! 128 real*4 PTG_FOV_ELEV_THM(2) ! 8 real*4 PTG_INST2MACS_ELEV(2) ! 8 real*4 PTG_LIMB_PT(3) ! 12

19 DRAFT / SSAI

real*4 REF_EARTH_RADIUS ! 4 real*4 REF_LAT ! 4 real*4 REF_LONG ! 4 real*4 REF_SOLAR_TIME ! 4 real*4 REF_SOLAR_ZEN ! 4 real*4 ROLLRATE_UARS(ifc_max) ! 128 real*4 ROLL_UARS(ifc_max) ! 128 real*4 SAT_GCRAD(ifc_max) ! 128 real*4 SAT_GEOD_ALT ! 4 real*4 SAT_GEOD_LAT ! 4 real*4 SAT_LONG ! 4 real*4 SAT_VEL(3) ! 12 real*4 TNGT_GEOD_ALT(ifc_max) ! 128 real*4 TNGT_GEOD_LAT(ifc_max) ! 128 real*4 TNGT_LONG(ifc_max) ! 128 real*4 TRANS_INST2ECI(3,3) ! 36 real*4 YPR(3) ! 12 real*4 YPR_RATE(3) ! 12

end structure ! 1,784 Bytes total structure /lvl1_rad_rec/

character*1 TYPE ! 1

union !\ map !data info !\ byte BAND_BANK !\ byte band_bank_pad(2) !\ end map ! 3 map !trailer info !/ byte SPARE(3) !/ end map !/ end union !/

integer*4 RECORDNO ! 4

union !\ map !data info !\ integer*4 MMAF_TIME(2) !\ end map ! 8 map !trailer info !/ integer*4 TRAILER_TIME(2) !/ end map !/ end union !/

integer*4 MMAFNO ! 4

real*4 PRD_TEMPS(16) ! 64

integer*4 DGAP_MMAF ! 4 integer*4 MANEUVER_STAT ! 4 integer*4 MLS_STATUS ! 4

integer*2 WALL_MMAF(ncmax) ! 180

20 DRAFT / SSAI

integer*2 WINDOW_RED_REFS(ncmax) ! 180 integer*2 WINDOW_RED_SZ(ncmax) ! 180

character*1 MMIF_STAT(ifc_max) ! 32 character*1 MMAF_STAT ! 1

logical*1 HGA_INTERFER ! 1

byte hga_pad(2) ! 2

integer*2 RAD_L1(ncmax, 2, ifc_max) ! 11,520

record /oa_buffer_rec/ oa_buffer ! 1,784

end structure ! Total: 14,276 Bytes record /lvl1_rad_rec/lvl1_rad

As in the case of Fortran, the software consists of one function routine which users can use to read the 3 level 1 header records and 1 routine which users can use to read the data records. Additional software in the form of a sample driver, a file name generation routine, and a file open routine are provided. A procedure is also provided to link the driver and routines. Details are given in the Appendix.

4.5.1 Level 1 C Header Record Access Function Routine (fth_rd_mls_l1_hdr_str_c)

The C function fth_rd_mls_l1_hdr_str_c (file fth_rd_mls_l1_hdr_str_c.c) reads the 3 MLS level 1 header (subtype MLSRAD). The MLS level 1 data file consists of fixed length records. The first 3 are header records.

Usage:

void fth_rd_mls_l1_hdr_str_c(int ird_rec, FILE *fptr,int in_recl, struct lvl1_hdr_rec *header, struct lvl1_uip_rec *uip, int* ierr) arguement list definitions

argument type i/o description ------ird_rec int i record number wanted. used in conjunction with itype. itype int i type of record to read. 1:header record

21 DRAFT / SSAI

2:suppl header record 3:data record

FILE*fptr file i file pointer for input file pointer in_recl int i number of 4-byte words in a record (3584 for MLS level 1) lvl1_rad_rec structure o structure for first part *lvl1_rad of header records. uip structure o structure for second part of header records. ierr int o error status 0:no error detected 1:error in in put record number. ------

4.5.2 Level 1 C Data Record Access Function Routine (fth_rd_mls_l1_str_c)

Function fth_rd_mls_l1_str_c (file fth_rd_mls_l1_str_c.c) reads the data records of the MLS level 1 file of subtype mlsrad. Access is direct. The first data record is record number 4.

Usage:

void fth_rd_mls_l1_str_c(int ird_rec, FILE *fptr,int in_recl, struct lvl1_rad_rec *lvl1_rad, int* ierr) arguement list definitions

argument type i/o description ------ird_rec int i record number wanted. used in conjunction with itype. itype int i type of record to read. 1:header record 2:suppl header record 3:data record

FILE*fptr file i file pointer for input file pointer in_recl int i number of 4-byte words in a record (3584 for MLS level 1) lvl1_rad_rec structure o structure for first part *lvl1_rad of header records.

22 DRAFT / SSAI uip structure o structure for second part of header records. ierr int o error status 0:no error detected 1:error in in put record number. ------

4.5.3 Level 1 C Access Array Transform Routines

Because C and Fortran storage for multidimensional arrays are not consistent with each other, software is needed to transform the multidimensional arrays after reading from disk so that they can be interpreted in the same manner by both C and Fortran. These functions are as follows (file names appear in parenthesis):

for_c_mtrx_2 (file for_c_mtrx_2.c) ch_for_c_mtrx_2 (file_ch_for_c_mtrx_2.c) int2_for_c_mtrx_3 (file int2_for_c_mtrx_3.c)

Users do not need to know how to use these routines, as they are called only by the function routine fth_read_mlsm_l1_c. Using the link procedure file given in Section 4.1.2.3 will automatically link these routines.

The required software consists of one routine that optionally reads the header record, a supplemental header record, or a data record.

4.6.1 Level 2 Fortran File Header Access Routine (fth_mls_l2_l2out_str)

Routine fth_mls_l2_l2out_str (file fth_mls_l2_l2out_str.for) optionally reads the header record, a supplemental header record, or a data record.

Usage:

call fth_mls_l2_l2out_str(l2in_lun,l2in_rec,lvl2_data,lvl2_hdr,nsv, & read_header_flag,lvl2_sv_info_rec,ios_rd)

Argument list

ARGUMENT TYPE I/O DESCRIPTION ------

L2IN_lun I*4 I LOGICAL UNIT NUMBER FOR FILE L2IN_rec I*4 I RECORD NUMBER TO READ. USED IN CONJUNCTION WITH READ_HEADER_FLAG.

23 DRAFT / SSAI

IF READ_HEADER_FLAG IS TRUE AND L2IN_REC = 1, THEN HEADER RECORD IS READ. IF READ_HEADER_FLAG IS TRUE AND L2IN_REC GT 1, THEN SUPPLEMENTAL RECORD IS READ. IF READ_HEADER_FLAG IS FALSE THEN A DATA RECORD IS READ. lvl2_data STRUCTURE O DATA RECORD lvl2_hdr STRUCTURE O HEADER RECORD nsv I I/O NUMBER OF SUPPLEMENTAL HEADER RECORDS read_header_flag LOGICAL I TRUE TO SELECT READ HEADER RECORDS, EITHER FIRST OR SUPPLMENTAL. IF FALSE, THEN READ DATA RECORD. LVL2_SV_INFO_REC STRUCTURE O STATE VECTOR RECORD (SUPPLEMENTAL HEADER RECORD)

The required software consists of one function that optionally reads the header record, a supplemental header record, or a data record.

4.7.1 Level 2 C File Header Access Routine (fth_read_mls_l2_str_c)

Function fth_read_mls_l2_str_c (file fth_read_mls_l2_str_c.c) optionally reads the header record, a supplemental header record, or a data record.

Usage:

Argument list description:

fth_read_mls_l2_str_c(int ird_rec, int itype, FILE *fptr, int in_recl,struct lvl2_header *lvl2_hdr, struct lvl2_sv_info *lvl2_sv_info_rec, struct lvl2_data *lvl2_data,int* ierr)

NAME TYPE I/O DESCRIPTION ------

argument type i/o description ------ird_rec int i record number wanted itype int i type of record. 1:header record 2:suppl header record 3:data record FILE*fptr file i file pointer for input file pointer in_recl int i number of 4-byte words in a

24 DRAFT / SSAI

record (3456 for MLS level 2) lvl2_hdr structure o structure for header record. lvl2_sv_info_rec structure o structure for supplental header records. lvl2_data structure o structure for data records ierr int o error status 0:no error detected 1:error in in put record number.

25 DRAFT / SSAI

Appendix: Additional Software

Sample software that uses the file access software described above is described in this Appendix. It should be noted that the software described here is not a formal part of the required software package, and is provided only as a convenience to users. The software described below consists of sample drivers, and functions and routines that generate file names and open the files. These are provided in Fortran and C.

This software, combined with the access software described earlier in the main text, is self-contained, and can be linked into executables. Link procedures are provided and described below.

A.1 Additional Level 0 Fortran Software

A.1.1 Level 0 Fortran File Open Routine (opn_l0_file)

The Fortran routine opn_l0_file (file opn_l0_file.for) opens a UARS level 0 file with the proper attributes. It calls routine gen_l0_name (file gen_l0_name.for) to generate the needed filenames based on user- input values such as the instrument acronym, the subtype, the uars day, and the data version, as described above. For each data version, there is a cycle number that is greater than or equal to 1. Users need not know the cycle number as long as the variable ICYC_MAX is set to be larger than the actual cycle number of the file. A value of 10 for ICYC_MAX is usually large enough. Routine opn_l0_file will begin with cycle number 1 and will increment cycle numbers until a file is successfully opened or until ICYC_MAX is reached. The data version number and the cycle number are determined by production processing. The data version number corresponds to the software version that was used to generate the file, and the cycle number is incremented each time reprocessing was needed for the same file using the same software.

Usage:

CALL OPN_L0_FILE(INSTR,IUARS_DAY,IVER_IN, & ICYC_MAX,ITYPE,IN_RECL,ICYC,LUN,FLNAME,IVAR,IDIRECT,IOS)

ARGUMENT LIST DESCRIPTION

ARGUMENT TYPE I/0 DESCRIPTION ------INSTR CH*12 I INSTRUMENT ACRONYM. e.g., claes, haloe, hrdi, isams, mls, pem, solstice, susima, susimb, windii, acrim, engineering, spacecraft, obc, quality IUARS_DAY I*4 I UARS DAY. IVER_IN I*4 I DATA VERSION. ICYC_MAX I*4 I MAXIMUM CYCLE NUMBER TO TRY. ITYPE I*4 I SET LAST 4 CHARACTERS OF INPUT FILE NAME. 1: PROD

26 DRAFT / SSAI

2: BNBE 3: BNLE -2: BVBE -3: BVLE IN_RECL I*4 I RECORD LENGTH (WORDS) OF FILE IF FIXED LENGTH. IF VALUE IS GT 0 FILE IS OPENED AS WITH RECL KEYWORD SET TO VALUE OF IN_RECL. ICYC I*4 I/O IF 0 ON INPUT, ROUTINE WILL TRY TO OPEN EXISTING FILE. CYCLES NUMBERS FROM 1 TO ICYC_MAX WIIL BE TRIED. IF EXISTING FILE IS FOUND, ICYC IS RETURNED. IF FILE NOT FOUND, ICYC IS SET BACK TO 0. LUN I*4 I/O LOGICAL UNIT NUMBER OF FILE. IF NOT ZERO ON INPUT, THE INPUT VALUE IS USED TO OPEN THE FILE. IF ZERO ON INPUT, LUN WILL BE SET TO 95 (INPUT) IF ICYC IS 0, AND TO 96 (OUTPUT) IF ICYC IS NOT 0. FLNAME CH*50 O FLNAME OF FILE. IVAR I*4 I IF O, OPEN FOR FIXED RECORD LENGTH IF -1, OPEN WITH KEYWORD RECORDTYPE SET TO 'SEGMENTED' IF -2, OPEN WITH KEYWORD RECORDTYPE SET TO 'VARIABLE' IDIRECT I*4 I INPUT 0:SEQUENTIAL ACCESS,1:DIRECT IOS I*4 O STATUS.

A.1.2 Level 0 Fortran File Name Routine (gen_l0_name)

Routine gen_l0_name (file gen_l0_name.for) generates the correct file name based on user-input values of the instrument and subtype acronyms, the UARS day number, and the file data version.

This routine is called only by opn_l0_file, and users only need to link this routine.

Usage:

CALL GEN_L0_NAME(INSTR,IUARS_DAY,FNAME,IVER,ICYC, & ITYPE)

ARGUMENT DESCRIPTION:

ARGUMENT TYPE I/0 DESCRIPTION ------INSTR CH*12 I INSTRUMENT ACRONYM. IUARS_DAY I*4 I UARS DAY. IVER I*4 I DATA VERSION. ICYC I*4 I DATA VERSION. FNAME CH*50 O filename

27 DRAFT / SSAI

A.1.3 Level 0 Sample Fortran Driver and Link Procedure

An example of a driver that uses fth_readl0 (file fth_readl0.for) to read all types of level 0 files is provided and given in file

get_l0.for

The command/script file

get_l0.com can be used to link and generate an executable named

get_l0.exe

For linking, in addition to the sample driver (file get_l0.for), the routines fth_readl0 (file fth_readl0.for), opn_l0_file (file opn_l0_file.for), gen_l0_name (file gen_l0_name.for), swap16 (file swap16.for), swap32 (file swap32.for), and swap64 (file swap64.for), (as noted earlier) are needed as well.

Upon running program get_l0.exe interactively, the following prompt appears on the screen:

ENTER FILE TYPE NUMBER 1:CLAES,2:HALOE,3:HRDI,4:ISAMS,5:MLS,6:PEM 7:SOLSTICE,8:SUSIMA,9:SUSIMB,10:WINDII,11:ACRIM 12:ENGINEERING,13:SPACECRAFT,14:OBC,15:QUALITY ENTER UARS DAY ENTER FIRST DATA RECORD NUMBER, LAST DATA RECORD NUMBER' (-1 FOR BOTH TO DO ALL DATA RECORDS) DATA VERSION NUMBER,WRITE ASCI FILE[0/1] SWAP BYTES[0/1]

An example of a user input to this prompt is

12 130 1 10 2 1 1

The different input variables are separated with blanks. As described in the prompt, the first input, '12', selects the ENGINEERING file to open and read. The 130 selects the UARS day to read (there is one file for each day). Recall that UARS day number 1 is September 12, 1991, and January 1 1992 corresponds to UARS day 112. The '1 10' selects the first and last data records wanted (in this case the first 10 records). The next input, '2', is the file data version number. The next to last input, '1', means that an output file (in ASCII) of selected data will be written. The last input, also '1', is used for big endian computers, and a value of '0' is input for little endian systems.

With the above input, the program will read the first 10 data records of the level 0 data file named

engineering_l0_d0130.v0002_c01_prod and write a text file named

28 DRAFT / SSAI

engineering_l0_d0130.v0002_c01_asci containing certain portions of data from the 10 selected records.

UARS file name conventions have been described in Section 1.1. Here, the output file name is the same as the input level 0 file except for the last 4 characters. In the above example, the user need not know the cycle number because the software first tries cycle number 1 and if needed, increments the cycle number until the file is found, or until a preset maximum is reached. This is the value of icyc_max and is currently set to 5. See the previous subsection on routine OPN_L0_FILE for more details.

A.2 Additional Level 0 C Software.

A.2.1 Level 0 C File Open Function Routine (opn_l0_file_c)

The C function routine opn_l0_file_c (file opn_l0_file_c.c) opens a UARS level 0 file with the proper attributes. It calls gen_l0_name_c (file gen_l0_name_c.c) to generate the file name based on user-input values such as the acronyms for instrument and parameter, the uars day number, and the data version number, which have been described above. The use of this function parallels that for the Fortran version, which is described in Section A.1.1.

Usage:

void opn_l0_file_c(char *instr,int iuars_day,int iver_in, int icyc_max,int itype_rd,int in_recl,int *icyc,FILE **fp_rd, char *flname_rd,int *ios_rd);

opn_l0_file_c(instr,iuars_day,iver_in,icyc_max,itype_rd, in_recl,&icyc,&fp_rd,flname_rd,&ios_rd);

arguement type i/0 description ------instr ch*12 i instrument acronym. iuars_day i*4 i uars day. (e.g., sept 12, 1991 is uars day 1, jan 1 1992 is uars day 112; jan 1 1993 is uars day 478) iver_in i*4 i data version. icyc_max i*4 i maximum cycle number to try. itype i*4 i set last 4 characters of input file name. 1: prod 2: bnbe 3: bnle 4: asci in_recl i*4 i record length (bytes) of file if fixed length. icyc i*4 i/o nominally 0 on input. if 0 on input, routine will assume an existing file. cycles number will be incremented from 1 to icyc_max until

29 DRAFT / SSAI

success. if existing file is found, icyc is returned. ifp FILE** o pointer to file pointer flname ch*50 o flname of file. ios i*4 o status of open.

A.2.2 Level 0 C File Name Function Routine (gen_l0_name_c)

Function routine gen_l0_name_c (file gen_l0_name_c.c) generates the correct file name based on input values of the instrument and subtype acronyms, the UARS day number, and the file data version. This routine is called only by opn_l0_file_c.c, and users only need to link this routine.

A.2.3 Level 0 Sample C Driver and Link Procedure

An example of a driver that uses mcb_readl0_c to read all types of level 0 files is provided and given in file

get_l0_c.c

The command/script file

cclink_get_l0.com can be used to compile, link, and generate an executable named

get_l0_c.x

For linking, in addition to the sample driver (file get_l0_c.c), the functions mcb_readl0_c (file mcb_readl0_c.c), opn_l0_file_c (file opn_l0_file_c.c), gen_l0_name_c (file gen_l0_name_c.c), swap16_c (file swap16_c.c), swap32_c (file swap32_c.c), and swap64_c (file swap64_c.c) (noted earlier) are needed as well.

Upon running program get_l0_c.x interactively, the following prompt appears on the screen:

ENTER INSTRUMENT NUMBER 1:CLAES,2:HALOE,3:HRDI,4:ISAMS,5:MLS,6:PEM 7:SOLSTICE,8:SUSIMA,9:SUSIMB,10:WINDII,11:ACRIM 12:ENGINEERING,13:SPACECRAFT,14:OBC,15:QUALITY

ENTER UARS DAY ENTER FIRST DATA RECORD NUMBER, LAST DATA RECORD NUMBER (-1 FOR BOTH TO DO ALL DATA RECORDS) DATA VERSION NUMBER WRITE ASCI FILE (0=NO,1=YES,2=to SCREEN) SWAP BYTES (0=NO,1=YES)

30 DRAFT / SSAI

5 486 1 3 2 1 1

The different input variables are separated with blanks. As described in the prompt, the first input, '5', selects the MLS file to open and read. The '486' selects the UARS day to read (there is one file for each day). Recall that UARS day number 1 is September 12, 1991, and January 1 1992 corresponds to UARS day 112. The '1 3' selects the first and last data records wanted (in this case the first 3 records). The next input, '2', is the file data version number. The next to last input, '1', means that an ASCII output file of selected data will be written. The last input, also '1', is used for big endian computers, and a value of '0' is input for little endian systems.

With the above input, the program will read the first 3 data records of the level 0 data file named

mls_l0_d0486.v0002_c01_prod and write a text file named

mls_l0_d0486.v0002_c01_asci containing certain portions of data from the 3 selected records.

UARS file name conventions have been described in Section 1.1. Here, the output file name is the same as the input level 0 file except for the last 4 characters. In the above example, the user need not know the cycle number because the software first tries cycle number 1 and if needed, increments the cycle number until the file is found, or until a preset maximum is reached. This is the value of icyc_max and is currently set to 5. See the previous subsection on routine opn_l0_file_c for more details.

A.3 Additional Level 1 Fortran Software.

A.3.1 Level 1 Fortran File Open Routine (opn_l1_file)

The Fortran routine opn_l1_file (file opn_l1_file.for) opens a UARS level 1 file with the proper attributes. It calls routine gen_l1_name (file gen_l1_name.for) to generate the needed file name based on user- input values such as acronyms for the instrument and parameter, the uars day, and the data version number. Details are the same as described above in Section A.1.1 for the opn_l0_file routine. An example of using this routine is given by the sample driver in file get_claes_l1_claes_ns.for noted above.

Usage:

CALL OPN_L1_FILE(INSTR,PARAM,IUARS_DAY,IVER_IN, & ICYC_MAX,ITYPE_IN,IN_RECL,ICYC,LUN,FLNAME,IVAR, & IDIRECT,IOS)

31 DRAFT / SSAI

ARGUMENT TYPE I/0 DESCRIPTION ------INSTR CH*12 I INSTRUMENT ACRONYM. PARAM CH*12 I MEASURE PARAMETER. IUARS_DAY I*4 I UARS DAY. (E.G., SEPT 12, 1991 IS UARS DAY 1, JAN 1 1992 IS UARS DAY 112; JAN 1 1993 IS UARS DAY 478) IVER_IN I*4 I DATA VERSION NUMBER. ICYC_MAX I*4 I MAXIMUM DATA CYCLE NUMBER TO TRY. ITYPE_IN I*4 I USED TO DETERMINE LAST 4 CHARACTERS OF FILE NAME: 0 OR 1: PROD 2: BNBE 3: BNLE 4: ASCI ALSO USED FOR CONVERSION IF APPLICABLE. 1: NOCONVERSION 2: CONVERT = 'BIG ENDIAN' 3: CONVERT = 'LITTLE ENDIAN' IN_RECL I*4 I RECORD LENGTH (WORDS) OF FILE IF FIXED LENGTH. IF VALUE IS GT 0 FILE IS OPENED WITH RECL KEYWORD SET TO VALUE OF IN_RECL. IF VALUE IS ZERO, FILE WILL BE OPENED WITHOUT RECL KEYWORD. AND DEFAULT IS USED. FOR VARIABLE RECORDS, VALUES FOR VMS ARE: SEGMENTED:2048(BYTES) OTHERS:133 ICYC I*4 I/O SHOULD BE NOMINALLY SET TO 0. IF 0 ON INPUT, ROUTINE WILL TRY TO OPEN EXISTING FILE. CYCLES NUMBERS FROM 1 TO ICYC_MAX WIIL BE TRIED. IF EXISTING FILE IS FOUND,ICYC IS RETURNED. IF FILE NOT FOUND, ICYC IS INCREMENTED BY 1 UP TO ICYC_MAX. IF NOT ZERO ON INPUT, FILE IS ASSUMED NOT TO EXIST AND A NEW FILE IS OPENED USING THE VALUE IF ICYC. LUN I*4 I/O LOGICAL UNIT NUMBER OF FILE. IF NOT ZERO ON INPUT, THE

32 DRAFT / SSAI

INPUT VALUE IS USED TO OPEN THE FILE. IF ZERO ON INPUT, LUN WILL BE SET TO 95 (INPUT) IF ICYC IS 0. AND TO 96 (OUTPUT) IF ICYC IS NOT 0. FLNAME CH*50 O FLNAME OF FILE. IVAR I*4 I IF O, OPEN FOR FIXED RECORD LENGTH, AND IS THE CASE FOR CLAES. IF -1, OPEN WITH KEYWORD RECORDTYPE SET TO 'SEGMENTED'(VMS ONLY) IF -2, OPEN WITH KEYWORD RECORDTYPE SET TO 'VARIABLE' IDIRECT I*4 I INPUT 0:SEQUENTIAL ACCESS,1:DIRECT. DIRECT IS APPLICABLE TO CLAES IOS I*4 O STATUS AFTER ATTEMPT TO OPEN.

Routine gen_l1_name (file gen_l1_name.for) generates the correct file name based on user-input values of the instrument and subtype acronyms, the UARS day number, and the file data version number.

This routine is called only by opn_l1_file, and users only need to link this routine.

An example of a driver that uses the Fortran level 1 access routines is in file

get_mls_l1_mlsrad_str.for

A sample link procedure is given in file

get_mls_l1_mlsrad_str.com

Execution of this file will produce an executable in file

get_mls_l1_mlsrad_str.exe

Upon running the executable interactively, the following prompt appears:

ENTER INSTR,SUBTYPE(LWR CASE,SNGL QUOTES) BEGIN UARS DAY,END UARS DAY ENTER FIRST DATA RECORD NUMBER, LAST DATA RECORD NUMBER

33 DRAFT / SSAI

(-1 TO DO ALL DATA RECORDS) DATA VERSION IN FILE TYPE (0:VMS .PROD,1:PRO0,2:BIG ENDIAN,3:LITTLE) WRITE SELECTED DATA TO PLOT?[0:NO,1:YES]

Upon running program GET_MLS_L1_DATA_STR.EXE interactively, the following prompt appears on the screen:

ENTER INSTR,PARAM(LWR CASE,SNGL QUOTES, PARAM IS DATA) BEGIN UARS DAY,END UARS DAY ENTER FIRST DATA RECORD NUMBER, LAST DATA RECORD NUMBER (-1 TO DO ALL DATA RECORDS) FILE DATA VERSION FILE TYPE:0:VMS(PROD),1:VMS(.PRO0),2:BIG ENDIAN,3:LITTLE WRITE SELECTED DATA TO PLOT?[0:NO,1:YES]

'mls' 'data' 120 120 1 10 12 2 1

The different input variables are separated with blanks. The first string is the mls instrument acronym, and the second is the subtype acronym. The '120 120' selects the begin and end UARS days to read (there is one file for each day). Here, only the file for UARS day 120 is processed. UARS day number 1 is September 12, 1991, and January 1 1992 corresponds to UARS day 112. The '1 10' selects the first and last data records wanted (in this case the first 10 records). The '12' is the file data version number, and the '2' is used for the file name generation ( big endian). The last input, namely, '1' chooses the option to write the selected records to a text file for analysis. A '0' does not produce a file.

With the above input, the program will read the header record and the first 10 data records of the level 1 data file named

mls_l1_smlsrad_d0120.v0012_c01_bnbe and write a text file named

mls_l1_smlsrad_d0120.v0012_c01_asci containing certain portions of data from the 10 selected records.

A.4 Additional Level 1 C Software.

A.4.1 Level 1 C File Open Function (opn_l1_file_c)

The C function routine opn_l1_file_c (file opn_l1_file_c.c) opens a UARS level 1 file with the proper attributes. It calls routine gen_l1_name_c (file gen_l1_name_c.c) to generate the filename based on input values such as acronyms for the instrument (i.e., claes), parameter (i.e., claes), uars day, and the data version number, which

34 DRAFT / SSAI have been described previously. Details are the same as described above in Section A.1.1 for the opn_l0_file routine.

Usage:

opn_l1_file_c(char* instr,char* param,int iuars_day, int iver_in,int icyc_max,int itype_in, int in_recl,int* icyc,FILE** ifp, char* flname,int* ios)

Argument list description: argument type i/0 description ------instr char[12] i instrument acronym. param char[12] i measure parameter. iuars_day int i uars day. (e.g., sept 12, 1991 is uars day 1, jan 1 1992 is uars day 112; jan 1 1993 is uars day 478) iver_in int i data version. icyc_max int i maximum cycle number to try. itype int i set last 4 characters of input file name. 1: prod 2: bnbe 3: bnle 4: asci in_recl int i record length (bytes) of file if fixed length. icyc int i/o nominally 0 on input. if 0 on input, routine will assume an existing file. Cycles number will be incremented from 1 to icyc_max until success. if existing file is found,icyc is returned. ifp FILE** o pointer to file pointer flname char[50] o flname of file. ios int o status of open.

A.4.2 Level 1 C File Name Function (gen_l1_name_c)

The function routine in file gen_l1_name_c.c generates the file name based on input values of the instrument and subtype acronyms, the UARS day number, and the file data version. This routine is called only by opn_l1_file_c.c, and users only need to link this routine.

A sample driver that uses the above functions is in file

35 DRAFT / SSAI

get_mls_l1_mlsrad_str_c.c.

Upon executing the link procedure is in file

get_mls_l1_mlsrad_str_c.com an executable file named

get_mls_l1_mlsrad_str_c.exe is produced.

Use of this C program is similar to that for the corresponding Fortran program described earlier. Details are repeated here for convenience.

Upon interactively running the program

get_mls_l1_mlsrad_str_c.exe the following appears on the screen: enter instr,param(lwr case,no quotes) begin uars day,end uars day enter first data record number, last data record number (negative to do all data records) data version in file type (default:0 for .prod, 2:big endian) write output (0:no,1:yes)

An example of a user input to this prompt is mls mlsrad 120 120 1 10 4 2 1

The different input variables are separated with blanks. The first string is the mls instrument acronym, the second is the subtype acronym. The '120 120' selects the begin and end UARS days (there is one file for each day) to read. UARS day number 1 is September 12, 1991; January 1 1992 corresponds to UARS day 112. The input '1 10' selects the first and last data records wanted (in this case the first 10 records). The '4' gives the file data version number, the '2' is used for the file name generation (2 denotes big endian). The last input, namely '1' chooses the option to write the portions of the selected records to a text file for analysis. A '0' does not produce a file.

With the above input, the program will read the 3 header records and the first 10 data records of the level 1 data file named

mls_l1_smlsrad_d0120.v0004_c01_bnbe and write a text file named

mls_l1_smlsrad_d0120.v0004_c01_asci containing certain portions of data from the 10 selected records.

36 DRAFT / SSAI

A.5 Additional Level 2 Fortran Software

A.5.1 Level 2 Fortran File Open Routine(opn_l2_file)

The Fortran routine opn_l2_file.for opens a UARS level 2 file with the proper attributes. It calls routine GEN_L2_NAME to generate the needed filename based on input values such as acronyms for the instrument and parameter, for the uars day number, and the data version number, which have been described above. Details are the same as described above in Section A.1.1 for the opn_l0_file routine. An example of usage is given by the sample driver GET_CLAES_L2_CLAES_NS.FOR.

Usage:

CALL OPN_L2_FILE(INSTR,PARAM,IUARS_DAY,IVER_IN, & ICYC_MAX,ITYPE_IN,IN_RECL,ICYC,LUN,FLNAME,IVAR, & IDIRECT,IOS)

ARGUMENT TYPE I/0 DESCRIPTION ------INSTR CH*12 I INSTRUMENT ACRONYM. PARAM CH*12 I MEASURE PARAMETER. IUARS_DAY I*4 I UARS DAY. (E.G., SEPT 12, 1991 IS UARS DAY 1, JAN 1 1992 IS UARS DAY 112; JAN 1 1993 IS UARS DAY 478) IVER_IN I*4 I DATA VERSION NUMBER. ICYC_MAX I*4 I MAXIMUM DATA CYCLE NUMBER TO TRY. ITYPE_IN I*4 I USED TO DETERMINE LAST 4 CHARACTERS OF FILE NAME: 0 OR 1: PROD 2: BNBE 3: BNLE 4: ASCI ALSO USED FOR CONVERSION IF APPLICABLE. 1: NOCONVERSION 2: CONVERT = 'BIG ENDIAN' 3: CONVERT = 'LITTLE ENDIAN' IN_RECL I*4 I RECORD LENGTH (WORDS) OF FILE IF FIXED LENGTH. IF VALUE IS GT 0 FILE IS OPENED WITH RECL KEYWORD SET TO VALUE OF IN_RECL. IF VALUE IS ZERO, FILE WILL BE OPENED WITHOUT RECL KEYWORD, AND DEFAULT IS USED. FOR VARIABLE RECORDS,VALUES FOR VMS ARE: DEFAULTS:SEGMENTED:2048(BYTES) OTHERS:133

37 DRAFT / SSAI

ICYC I*4 I/O SHOULD BE NOMINALLY SET TO 0. IF 0 ON INPUT, ROUTINE WILL TRY TO OPEN EXISTING FILE. CYCLES NUMBERS FROM 1 TO ICYC_MAX WIIL BE TRIED. IF EXISTING FILE IS FOUND, ICYC IS RETURNED. IF FILE NOT FOUND, ICYC IS INCREMENTED BY 1 UP TO ICYC_MAX. IF NOT ZERO ON INPUT, FILE IS ASSUMED NOT TO EXIST AND A NEW FILE IS OPENED USING THE VALUE IF ICYC. LUN I*4 I/O LOGICAL UNIT NUMBER OF FILE. IF NOT ZERO ON INPUT, THE INPUT VALUE IS USED TO OPEN THE FILE. IF ZERO ON INPUT, LUN WILL BE SET TO 95 (INPUT) IF ICYC IS 0. AND TO 96(OUTPUT) IF ICYC IS NOT 0. FLNAME CH*50 O FLNAME OF FILE. IVAR I*4 I IF O, OPEN FOR FIXED RECORD LENGTH IF -1, OPEN WITH KEYWORD RECORDTYPE SET TO 'SEGMENTED' IF -2, OPEN WITH KEYWORD RECORDTYPE SET TO 'VARIABLE' IDIRECT I*4 I INPUT 0:SEQUENTIAL ACCESS,1:DIRECT IOS I*4 O STATUS AFTER ATTEMPT TO OPEN.

Routine gen_l2_name (file gen_l2_name.for) generates the correct file name based on input values of the instrument and subtype acronyms, the UARS day number, and the file data version number. This routine is called only by OPN_L2_FILE.FOR, and users only need to link this routine.

The file name of the sample driver is

get_mls_l2_l2out_str.for and the link file is given in

get_mls_l2_l2out_str.com

Execution of the link file produces an executable in file

get_mls_l2_l2out_str.exe

Upon running the executable interactively, the following prompt appears on the screen:

38 DRAFT / SSAI

ENTER INSTR,SUBTYPE(LWR CASE,SNGL QUOTES) BEGIN UARS DAY,END UARS DAY ENTER FIRST DATA RECORD NUMBER, LAST DATA RECORD NUMBER (-1 TO DO ALL DATA RECORDS) DATA VERSION IN FILE TYPE (0:VMS .PROD,1:PRO0,2:BIG ENDIAN,3:LITTLE) WRITE SELECTED DATA TO PLOT?[0:NO,1:YES]

'mls' 'l2out' 372 372 1 10 4 2 1

The different input variables are separated with blanks. The first string is the mls instrument acronym, the second is the subtype acronym. The '372 372' selects the begin and end UARS days to read (there is one file for each day). UARS day number 1 is September 12, 1991; January 1 1992 corresponds to UARS day 112. The '1 10' selects data records 1 to 10 to read. The '4' is the file data version number, the '2' is used for the file name generation (2 for big endian). The next to last input, namely '1' chooses the option to write the 10 selected records to a text file for analysis. A '0' does not produce a file.

With the above input, the program will read the level 2 ozone data file named

mls_l2_sl2out_d0372.v0004_c01_bnbe and write a text file

mls_l1_sl2out_d0372.v0012_c01_asci containing certain portions of data from the selected records.

A.6 Additional Level 2 C Software

A.6.1 Level 2 C File Open Code (opn_l2_file_c)

The C function routine opn_l2_file_c (file opn_l2_file_c.c) opens a UARS level 2 file with the proper attributes. It calls function gen_l2_name_c (file gen_l2_name_c.c) to generate the file name based on input values such as acronyms for the instrument and the parameter, for the uars day number, and the data version number, which have been described above. Details are the same as described above in Section A.1.1 for the opn_l0_file routine.

Usage:

opn_l2_file_c(char* instr,char* param,int iuars_day,int iver_in,int icyc_max,int itype_in,int in_recl,int* icyc,FILE** ifp,char* flname,int* ios)

39 DRAFT / SSAI

argument type i/0 description ------instr char[12] i instrument acronym. param char[12] i measure parameter. iuars_day int i uars day. (e.g., sept 12, 1991 is uars day 1, jan 1 1992 is uars day 112; jan 1 1993 is uars day 478) iver_in int i data version. icyc_max int i maximum cycle number to try. Itype int i set last 4 characters of input file name. 1: prod 2: bnbe 3: bnle 4: asci in_recl int i record length (bytes) of file if fixed length. icyc int i/o nominally 0 on input. if 0 on input, routine will assume an existing file. Cycles number will be incremented from 1 to icyc_max until success. if existing file is found, icyc is returned. ifp FILE** o pointer to file pointer flname char[50] o flname of file. ios int o status of open.

A.6.2 Level 2 C File Name Function (gen_l2_name_c)

Function gen_l2_name_c (file gen_l2_name_c.c) generates the correct file name based on input values of the instrument and subtype acronyms, the UARS day number, and the file data version. This routine is called only by opn_l2_file_c.c, and users only need to link this routine.

A sample driver to use the above functions is provided in file

get_mls_l2_all_str_c.c and the link file is given in

get_mls_l2_all_str_c.com

Execution of the link file produces an executable in file

40 DRAFT / SSAI

get_mls_l2_all_str_c.exe

Use of this C program is similar to that for the corresponding Fortran program described earlier. Details are repeated here for convenience.

Upon running the executable interactively, the following prompt appears on the screen: enter instr,param(lwr case,no quotes) begin uars day,end uars day enter first data record number, last data record number (negative to do all data records) data version in file type (def:0:.prod,2:big endian,3:little endian) write output (0:no,1:yes)

An example of a user input to this prompt is mls l2out 372 372 1 10 4 2 1

The different input variables are separated with blanks(commas will work as well). The first string is the mls instrument acronym, the second is the subtype acronym. The input '372 372' selects the begin and end UARS days to read (there is one file for each day). UARS day number 1 is September 12, 1991 January 1 1992 corresponds to UARS day 112. The '1 10' selects data records 1 to 10 to read. The '4' is the file data version number, the '2' is used for the file name generation (big endian). The next to last input, namely '1' chooses the option to write the 10 selected records to a text file for analysis. A '0' does not produce a file.

With the above input, the program will read the level 2 ozone data file named

mls_l2_sl2out_d0372.v0004_c01_bnbe and write a text file

mls_l2_sl2out_d0372.v0004_c01_asci containing certain portions of data from the selected records.