Document title: SUN UNIX program 4S2ASC.F to convert flat files to ASCII for NDADS ISEE1 and ISEE2 4-second magnetometer flat-file datatype MAG_4S_FF Project: ISEE1 and ISEE2 NDADS Datatype: MAG_4S_FF Super-EID: SOFTWARE There may be other documents also identified by this super-EID. NDADS filename: 4S2ASC.F TRF entry: b46640.txt in NSSDC's controlled digital document library, Mar. 1998. Document text follows: ---------------------- C * ------------------------------------------------------------------------- * C * * C * 4s2asc.f - Program to read UCLA-IGPP flat files containing ISEE 4- * C * second magnetic field averages and write an ascii text file * C * of the data. * C * * C * This program reads files containing 4-second magnetic field * C * averages in spacecraft coordinates of the International * C * Sun-Earth Explorers (ISEE) 1 and 2 spacecraft of the United * C * States National Aeronautics and Space Adminstration (NASA). * C * This program writes both the meta data portion of the 4- * C * second flat file and the binary data portion of the flat * C * file as ASCII text to a user specified output file. * C * * C * A flat file is made up of a pair of files: an ASCII file * C * containing meta data with the file type extension ".ffh" * C * (for flat file header); and a data file containing binary * C * values with the file type extension ".ffd" (for flat file * C * data). * C * * C * This program assumes that the input flat files were FTPed * C * from a DEC VAX_VMS system and so includes the necessary * C * software to convert floating-point values from DEC VAX_VMS * C * format to IEEE format used on Sun_UNIX systems. * C * * C * At the end of this code there is a list that includes the * C * name of each data column in a 4-second flat file along with * C * a brief description of each data item. * C * * C * Copyright (c) 1975-94 Regents of the University of California. * C * All Rights Reserved. * C * * C * Redistribution and use in source and binary forms are permitted * C * provided that the above copyright notice and this paragraph are * C * duplicated in all such forms and that any documentation, advertising * C * materials, and other materials related to such distribution and use * C * acknowledge that the software was developed by the University of * C * California, Los Angeles. The name of the University may not be used * C * to endorse or promote products derived from this software without * C * specific prior written permission. THIS SOFTWARE IS PROVIDED "AS IS" * C * AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT * C * LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * C * FOR A PARTICULAR PURPOSE. * C * * C * For information about this software please contact: * C * * C * Principal Investigator: * C * Christopher Russell * C * UCLA - Institute of Geophysics and Planetary Physics * C * 6871 Slichter Hall * C * Los Angeles, Ca. 90024-1567 * C * INTERNET e-mail: ctrussell@igpp.ucla.edu * C * NSI/DECnet e-mail: BRUNET::CTRUSSELL * C * Telephone: (310) 825-3188 * C * * C * Programmer: * C * Harry Herbert * C * UCLA - Institute of Geophysics and Planetary Physics * C * 5833 Slichter Hall * C * Los Angeles, Ca. 90024-1567 * C * INTERNET e-mail: hherbert@igpp.ucla.edu * C * NSI/DECnet e-mail: BRUNET::HARRY * C * Telephone: (310) 825-9030 * C * * C * ------------------------------------------------------------------------- * c FORTRAN 77 requires that if the program statement exists that the first c character of the program name be alphabetic (A - Z). Since the line is c only used for internal reference, it is commented out here. The operating c system compilers and linkers have no problem with this program name. c program 4s2asc c "fname" - the name of the input flat file c "aname" - the name of the output ASCII file c "trimlen" - an integer function that returns the length of a string with c trailing blanks removed c "fflen" - the character length of the input file name contained in "fname" character*64 fname, aname integer trimlen, fflen c Print out introductory information about the program. write(*,'(a)') > ' Program: 4s2asc ', > ' ', > ' ''4s2asc'' reads UCLA-IGPP flat files containing 4- ', > ' second ISEE magnetic field averages in spacecraft ', > ' coordinates and writes both the meta data and binary data ', > ' files as ASCII text to a user specified output file. ', > ' ', > ' A UCLA-IGPP flat file is made up of two files: a file', > ' with the type extension ''.ffh'' (for flat file header) has', > ' ASCII meta data; and a file with the type extension ''.ffd''', > ' (for flat file data) has binary data values. ', > ' ' write(*,'(a)') > ' The naming convention for the 4-second data files are ', > ' ''4s#XXXX.ffh'' and ''4s#XXXX.ffd'' where # is the ISEE ', > ' spacecraft number, either 1 or 2, and XXXX is the four ', > ' digit orbit number, with leading zeroes as needed. For ', > ' example, ''4s10001'' has data for ISEE-1, orbit 1. ', > ' ', > ' The 4-second flat files read by this program are ', > ' about 1.25 Mbytes each. The ASCII version of the same data', > ' made by this program is about 4.25 Mbytes. ', > ' ' c Get the name of the name of the 4-second input flat file from the user. write (*,*) 'Enter the name of the 4-second input flat file:' read (*,'(a)',iostat=ierr) fname if(ierr.ne.0) then write(*,*) 'Error',ierr,' getting name of input flat file' stop endif c Get the name of the output ASCII file from the user. write (*,*) 'Enter the name of the output ASCII file:' read (*,'(a)',iostat=ierr) aname if(ierr.ne.0) then write(*,*) 'Error',ierr,' getting name of output ASCII file' stop endif c Open the ASCII output file. open (10,file=aname,access='sequential',iostat=ierr,status='new') if(ierr.ne.0) then write(*,*) 'Error',ierr,' opening file ',aname stop endif c Get the length of the input flat file name. fflen = trimlen(fname) c Check to see if the user included the file type extension. If so, c ignore it by reducing the length parameter value. if(fname(fflen-3:fflen-1).eq.'.ff') fflen = fflen - 4 c Build the name of the ASCII header portion of the flat file pair. write(fname,'(a)') fname(1:fflen)//'.ffh' fflen = trimlen(fname) c Write out the meta data for the 4-second data file. call ffheader(fname(1:fflen)) c Build the name of the binary data portion of the flat file pair. write(fname(fflen:fflen),'(a)') 'd' c Write out the data in the 4-second data file. call ffdata(fname(1:fflen)) c Close the ASCII output file. 10 close(10) c Finish up. stop end c ----------------------------------------------------------------------------- c This routine reads the ASCII header portion of the flat file pair, c which contains meta data for the ISEE 4-second averaged magnetometer c data file. It then writes the information to an ASCII text file. subroutine ffheader(fname) character*(*) fname character*72 string c Open the ASCII header portion of the flat file pair. open (20,file=fname,access='direct',iostat=ierr,status='old', > form='unformatted',recl=72) if(ierr.ne.0) then write(*,*) 'Error',ierr,' opening file ',fname stop endif c Read then write the file attribute portion of the header file. do irec = 1, 6 read (20,rec=irec,iostat=ierr) string if(ierr.eq.0) then write(10,*) string else go to 10 endif end do c Read and modify the data column descriptor header line then write it out. read (20,rec=7,iostat=ierr) string if(ierr.eq.0) then string(51:72) = 'FORMAT' write(10,*) string else go to 10 endif c Read and modify the data column descriptor lines then write them out. irec = 8 do while (string.ne.'ABSTRACT') read (20,rec=irec,iostat=ierr) string if(ierr.eq.0) then if(string.ne.'ABSTRACT') then if(string(1:3).eq.'001') then string(15:50) = 'YR DOY MON DY HR MN SC MS' string(51:72) = 'I3.2,I4.3,5I3.2,I4.3' else string(51:72) = 'G13.5' endif endif write(10,*) string irec = irec + 1 else go to 10 endif end do c Read then write the abstract portion of the header file. do while (string.ne.'END') read (20,rec=irec,iostat=ierr) string if(ierr.eq.0) then write(10,*) string irec = irec + 1 else go to 10 endif end do c Close the ASCII header portion of the flat file pair. 10 close(20) c Define the flag values which are written out below as part of the meta data. iflag = 0 flag = 1.0e34 c Finish the meta data documentation by providing the FORTRAN format c statement used to write the data and a sample "record" of the flag c values for each data item. write(10,*) 'FORTRAN FORMAT:' write(10,*) '(I3.2,I4,3,5I3.2,I4.3,1X,4G13.5)' write(10,*) 'MISSING DATA FLAGS:' write(10,'(I3.2,I4.3,5I3.2,I4.3,1X,4G13.5,/)') > (iflag,i=1,8), (flag,i=1,4) write(10,*) 'DATA:' c Finish up. return end c ----------------------------------------------------------------------------- c This routine reads the binary data portion of the flat file pair, c which contains the ISEE 4-second averaged magnetometer data file. c It then writes the data to the same ASCII text file as the meta data. subroutine ffdata(fname) character*(*) fname real*4 record(6) real*8 time integer itime(8) equivalence (time,record(1)) c Open the binary data portion of the flat file pair. open (30,file=fname,access='direct',iostat=ierr,status='old', > form='unformatted',recl=24) if(ierr.ne.0) then write(*,*) 'Error',ierr,' opening file ',fname stop endif c Initialize the record counter. irec = 1 c Perform the following steps: c - Read the data records; c - Convert data values from VMS floating point to IEEE floating point; c - Convert the time to integer values; c - Verify that all flag values are consistent; c - Write out the data to the ASCII output file. do while (ierr.eq.0) read (30,rec=irec,iostat=ierr) record if(ierr.eq.0) then call r8decieee(time) do i = 3, 6 call r4decieee(record(i)) end do call tconi(time,itime) do i = 3, 6 if (record(i) .gt. 1.0e30 ) record(i) = 1.0e34 enddo write(10,'(I3.2,I4.3,5I3.2,I4.3,1X,4G13.5)') > (itime(i),i=1,8), (record(i),i=3,6) irec = irec + 1 endif end do c Close the binary data portion of the flat file pair. close(30) c Finish up. return end c ----------------------------------------------------------------------------- c This function returns the length of a FORTRAN character string with c trailing blanks removed. integer function trimlen (string) character string*(*),c*1 c Get the full length of the character string. i = len(string) c Start with the last character of the string and search forward until c a non-blank (or non-null) character is located. 10 if (i.eq.0) go to 20 c = string(i:i) if (c.ne.' '.and.c.ne.char(0)) go to 20 i = i - 1 go to 10 c Set the function equal to the length of the string excluding trailing c blanks. 20 trimlen = i c Finish up. return end c ----------------------------------------------------------------------------- c The following is a brief description of the contents of each of the data c columns in the 4-second flat file. c ----------------------------------------------------------------------------- c COL DATA DATA DATA FIELD DESCRIPTION c NUM NAME UNITS (COLUMN 1 IS REAL*8, COLUMNS 2-97 ARE REAL*4) c --- --------- --------- ----------------------------------------------------- c 001 TIME SECONDS Seconds since Jan. 1, 1966 at 00:00:00.000 c 002 BX SC NT 4 second average of Bx in spacecraft coordinates c 003 BY SC NT 4 second average of By in spacecraft coordinates c 004 BZ SC NT 4 second average of Bz in spacecraft coordinates c 005 BT NT 4 second average of total field c c NOTE: c The 4-byte fields of a 4-SECOND data record are initialized with a fill value c greater than 1.0E30, usually 1.0E34, and subsequently the geophysical values c are inserted. Thus if there is no data available for a given parameter that c particular field will contain the fill data value. c -----------------------------------------------------------------------------