C+ C NAME: C HOSRead C PURPOSE: C Read Helios for specific color and filter C CATEGORY: C I/O: Helios data C CALLING SEQUENCE: subroutine HOSRead(iD,cFile,nT,iT,NN,TT,PP,CC,FF,RR,LL,nnS,ZZ) C INPUTS: C iD integer identifies data properties C each bit in ID identifies a property defined in include file hos_e9.h C Bits are set by summing parameters defined in the include file. C Bits set for input are for: C - HOS__P_*: photometer selection (ignored if nS=1) C * is set to one of the following: 1, 2, 3, 12, 13, 23, 123 indicating C which photometers are selected. ALL can be used as alternative for 123. C - HOS__C_*: color selection C * is set to one of the following: 1, 2, 3, 12, 13, 23, 123 C indicating which colors are selected. ALL can be used as alternative for C 123. Instead of numbers 1, 2 or 3 the letters U, B and V can be used, C e.g, UB is an alternative for 12, etc. C - HOS__F_*: filter selection (ignored if nS=1) C * is set to one of the following: 1, 2, 3, 4 or 5 indicating which C filters are selected. POL can be used to select the three polarized C filters 1,2 and 4; CLR selects filter 4; PB selects filter 5; CLRPB C selects filters 4 and 5. ALL selects all five filters. C - HOS__NOT: negates the above photometer/color/filter selection C - HOS__AA or HOS__BB: spacecraft selection (ignored if name of input C file conforms to the standard Helios format). C - HOS__SWAP_SECT: indicate whether ordering of sectors uses modified sectors C numbers (resulting in swapping of sectors in output array; see PROCEDURE). C - HOS__SINGLE: indicate whether arrays NN, CC, FF, PP should be filled or not; C see PROCEDURE C cFile character*(*) name of Helios data file C if cFile has the standard form HyrLF_doy.* then a single color and filter C are read (determined from the file name) C nT integer maximum # records read into output arrays C nnS integer 2 <= nnS <= 32 or nnS = 1. C If nnS >= 2: # sectors to be returned in ZZ for 16 and 31 deg photometer C MUST BE EVEN. ODD VALUE WILL BE ROUNDED DOWN TO EVEN NUMBER C If nnS = 1 : forces reading of clear data for photometer 3 (i.e. photometers C 1 and 2 are ignored and pB also is ignored) C (Note that this overrides the photometer/filter setting in iD) C OUTPUTS: C iD integer several bits are modified C - HOS__P_*: if nnS = 1 then the HOS__P_3 bit is set; if the file contains data C for only one photometer, then the corresponding HOS__P_* bit is set. C - HOS__C_*: if the file contains data for only one color, then the C corresponding HOS__C_* bit is set. C - HOS__F_*: if the file contains data for only one filter, then the C corresponding HOS__F_* bit is set. C - HOS__AA or HOS__BB: if the name of the input file conforms to the standard C Helios format then the appropriate spacecraft bit is set C - HOS__NONORM: is set or cleared depending on the color entry in the 1st record C (set if > 100, indicating an unnormalized file, otherwise cleared) C C iT integer # records read into output arrays (<=nT) C NN(iT) integer record number (not filled if HOS__SINGLE set) C TT(iT) real day of year C PP(iT) integer photometer: 1=16 deg, 2=31 deg, 3=90 deg (not filled if HOS__SINGLE set and C only one photometer is selected. C CC(iT) integer color indices (not filled if HOS__SINGLE set and only one color is selected) C FF(iT) integer filter indices (not filled if HOS__SINGLE set and only one filter is selected) C RR(iT) real heliocentric distance (AU) C LL(iT) real topocentic ecliptic longitude (degrees) C ZZ(nnS,iT) real intensities C if nnS >= 2 then clear and pB for photometer 3 are stored in the first two C sector locations ZZ(1,*) and ZZ(2,*). C if nS =1 then only the clear data is stored in Z(1,*). C CALLS: C bOpenFile, bHOSName, iHOSRead, ArrR4Copy, iFreeLun, Say, iArrI4Total, cInt2Str C SEE ALSO: C HOSUpdate, HOSWrite C INCLUDE: include 'openfile.h' include 'hos_e9.h' C SIDE EFFECTS: C > An odd input value of nnS gives the same result as nnS-1, i.e. nnS will be rounded down C to the nearest even integer. In addition, nnS is kept inside the range [2,32]. C > Use HOSUpdate or HOSWrite to write data back to a disk file. C RESTRICTIONS: C > Adding parameters from the include file hos_e9.h to build the value for iD needs to be C done with some care: make sure to set each bit only once e.g. iD = HOS__P_1+HOS__P_ALL is WRONG C since it selects photometer 1 twice and will not give the expected response. C (the only really save way to combine the HOS__* parameters is using a logical or as e.g. C in iD = HOS__P_1 .or. HOS__P_ALL) C > The CC array always contains the value 1,2 or 3, even for unnormalized files. C Check the HOS__NONORM bit in the return value of iD, or use iHOSInfo to find out whether a file C contains unnormalized data (as indicated by a color entry 101, 102 or 103 in the file). C PROCEDURE: C > HOSRead will first try to use the input file name to open a file. If not succesfull C it will prompt for a file name. Not selecting a file results in program termination. C > The 90 degree intensity and pB are returned in Z(1,*) and Z(2,*), respectively, UNLESS nnS=1. C > if nnS = 1 the the clear intensity for photometer will be read into array Z(*) C ignoring the photometer and filter selection in iD. C > If nnS < 32, some of the anti-solar sectors are omitted, e.g. if nnS=28 then sectors C 15,16,17,18 will not be present. I.e. an even number of sectors centered on the solar C direction are returned in ZZ. C > If HOS__SWAP_SECT is not set in iD then sectors 1..nnS/2 and 33-nnS/2..32 (i.e. the first and the C last nnS/2 sectors) are returned in ZZ(1..nnS/2,*) and ZZ(nnS/2+1..nnS), respectively. C I.e. nnS sectors are stored in ZZ by increasing sector number: 1..nnS/2,33-nnS/1..33 C > If HOS__SWAP_SECT is set in iD then sectors 1..nnS/2 and 33-nnS/2..32 (i.e. the first and the C last nnS/2 sectors) are returned in ZZ(nnS/2+1..nnS) and ZZ(1..nnS/2,*), respectively. C I.e. nnS sectors are stored according to modified sector number (-15,..,+16) sweeping the sky C from west to east (Helios 1) or east to west (Helios 2). C > HOS__SINGLE can be set to save on memory requirements if single photometer/color/filter combinations C are read. If HOS__SINGLE is set then the record number array NN is not filled (note that this means that C HOSUpdate cannot be used to update the file); if only a single photometer is selected then only C PP(1) is filled; if a single color is selected then only CC(1) is filled; if a single filter is C selected only FF(1) is filled. In this case arguments NN, and one or more of PP, CC and FF can be C scalar variables. Note that it is the responsibility of the caller to make sure that the selection in C iD is indeed for a single photometer, color and/or filter. C MODIFICATION HISTORY: C SEP-1998, Paul Hick (UCSD/CASS) C MAY-2000, Paul Hick (UCSD/CASS; pphick@ucsd.edu), introduced bit-by-bit handling of iD C- integer iD character cFile*(*) integer nT integer iT integer NN(*) real TT(*) integer PP(*) integer CC(*) integer FF(*) real RR(*) real LL(*) integer nnS real ZZ(*) integer C integer F integer P real L real Z(32) integer Lst(11,3) logical bOpenFile logical bHOSName logical bSwap logical bArray logical bOnePP logical bOneCC logical bOneFF logical bFillPP logical bFillCC logical bFillFF character cInt2Str*14 character cSay*7 /'HOSRead'/ !------- ! Statement functions to check for single phot/color/filter selections bOnePP(kP) = kP .eq. HOS__P_1 .or. kP .eq. HOS__P_2 .or. kP .eq. HOS__P_3 bOneCC(kC) = kC .eq. HOS__C_1 .or. kC .eq. HOS__C_2 .or. kC .eq. HOS__C_3 bOneFF(kF) = kF .eq. HOS__F_1 .or. kF .eq. HOS__F_2 .or. kF .eq. HOS__F_3 .or. kF .eq. HOS__F_4 .or. kF .eq. HOS__F_5 iT = 0 !------- ! Check number of sectors (nS) to be read if (nnS .ge. 2) then nS = min(nnS/2*2,32) ! Round down to even number else ! nS=1: read photometer 3 clear intensity only nS = 1 iD = iD-iand(iD,HOS__P_ALL)+HOS__P_3 ! Force reading of photometer 3 iD = iD-iand(iD,HOS__F_ALL)+HOS__F_CLR end if !------- ! Split off photometer, color and filter selection kP = iand(iD,HOS__P_ALL) ! Photometer selection kC = iand(iD,HOS__C_ALL) ! Color selection kF = iand(iD,HOS__F_ALL) ! Filter selection !------- ! Photometer 3 only has clear and pB. Return if only phot 3 is requested without Clr or pB if (kP .eq. HOS__P_3 .and. iand(kF,HOS__F_CLRPB) .eq. 0) then call Say(cSay,'I','Phot. 3','Polarization filters 1,2,3 not available for 90 deg photometer') return end if if (bOpenFile(OPN__HOS+OPN__READONLY+OPN__TRYINPUT+OPN__STOP,iU,cFile,iRecl)) then !------- ! Use the file name to override the input spacecraft setting if possible if (bHOSName(cFile,iSc,iYr,C,F)) then if (iSc .eq. 1) then iD = iD-iand(iD,HOS__AB)+HOS__AA ! Set Helios A bit else iD = iD-iand(iD,HOS__AB)+HOS__BB ! Set Helios B bit end if end if bSwap = iand(iD, HOS__SWAP_SECT) .ne. 0 ! If set, use modified sectors in ZZ bArray = iand(iD, HOS__SINGLE ) .eq. 0 ! If set, fill CC and FF arrays bFillPP = bArray .or. .not. bOnePP(kP) bFillCC = bArray .or. .not. bOneCC(kC) bFillFF = bArray .or. .not. bOneFF(kF) iS = nS/2 ! Half # sectors to be extracted (will not be used if nS=1) iR = 0 nR = 0 do while (iT .lt. nT .and. iHOSRead(iD,iU,iRecl,iR,T,P,C,F,R,L,nS,Z) .eq. 0) nR = iR ! Last record successfully read iT = iT+1 if (iT .eq. 1) then iD = iD-iand(iD, HOS__NONORM) if (C .gt. 100) iD = iD+HOS__NONORM ! Set no-normalization bit end if C = mod(1*C,100) if (bArray) NN(iT) = iR TT(iT) = T if (bFillPP .or. iT .eq. 1) PP(iT) = P ! Fill photometer array if (bFillCC .or. iT .eq. 1) CC(iT) = C ! Fill color array if (bFillFF .or. iT .eq. 1) FF(iT) = F ! Fill filter array RR(iT) = R LL(iT) = L iZt = (iT-1)*nS+1 ! Starting position in ZZ where next data are put if (P .eq. 3) then call ArrR4Copy(min(nS,2),Z,ZZ(iZt)) else if (bSwap) then call ArrR4Copy(iS,Z ,ZZ(iZt+iS)) ! Swap 1st and last nS/2 sectors .. call ArrR4Copy(iS,Z(iS+1),ZZ(iZt )) ! .. in reverse order else call ArrR4Copy(nS,Z,ZZ(iZt)) ! Copy nS sectors into ZZ end if if (P .eq. 3) F = 1 F = 5*(P-1)+F Lst(F,C) = Lst(F,C)+1 end do !------- ! If output arrays are full, try to read one more record to determine whether any data were missed if (iT .eq. nT) then if (iHOSRead(iD,iU,iRecl,nR,T,P,C,F,R,L,nS,Z) .eq. 0) call Say(cSay,'W',cFile,'not all records read') end if iU = iFreeLun(iU) end if call Say(cSay,'I',cFile,'# records read: '//cInt2Str(iT)) if (iT .gt. 0) then !------- ! Check data read from file for presence of single phot, color or filter if (.not. bOnePP(kP)) then n1 = iArrI4Total(5,Lst(1,1),i)+iArrI4Total(5,Lst(1,2),i)+iArrI4Total(5,Lst(1,3),i) n2 = iArrI4Total(5,Lst(6,1),i)+iArrI4Total(5,Lst(6,2),i)+iArrI4Total(5,Lst(6,3),i) n3 = Lst(11,1)+Lst(11,2)+Lst(11,3) if ( n2+n3 .eq. 0) kP = HOS__P_1 ! Only UV available if (n1 +n3 .eq. 0) kP = HOS__P_2 ! Only blue available if (n1+n2 .eq. 0) kP = HOS__P_3 ! Only visual available if (bOnePP(kP)) then iD = iD-iand(iD, HOS__P_ALL)+kP call Say(cSay,'W','Photometers','Only one available: '//cInt2Str(kP)) end if end if if (.not. bOneCC(kC)) then n1 = iArrI4Total(11,Lst(1,1),i) n2 = iArrI4Total(11,Lst(1,2),i) n3 = iArrI4Total(11,Lst(1,3),i) if ( n2+n3 .eq. 0) kC = HOS__C_1 ! Only UV available if (n1 +n3 .eq. 0) kC = HOS__C_2 ! Only blue available if (n1+n2 .eq. 0) kC = HOS__C_3 ! Only visual available if (bOneCC(kC)) then iD = iD-iand(iD, HOS__C_ALL)+kC call Say(cSay,'W','Colors','Only one available: '//cInt2Str(kC)) end if end if if (.not. bOneFF(kF)) then !------- ! Photometer 1 and 2 n1 = Lst(1,1)+Lst( 6,1)+Lst(1,2)+Lst( 6,2)+Lst(1,3)+Lst( 6,3) n2 = Lst(2,1)+Lst( 7,1)+Lst(2,2)+Lst( 7,2)+Lst(2,3)+Lst( 7,3) n3 = Lst(3,1)+Lst( 8,1)+Lst(3,2)+Lst( 8,2)+Lst(3,3)+Lst( 8,3) n4 = Lst(4,1)+Lst( 9,1)+Lst(4,2)+Lst( 9,2)+Lst(4,3)+Lst( 9,3) n5 = Lst(5,1)+Lst(10,1)+Lst(5,2)+Lst(10,2)+Lst(5,3)+Lst(10,3) !------- ! Photometer 3: if nS = 1 then the pB data were not stored in ZZ. n4 = n4+Lst(11,1)+Lst(11,2)+Lst(11,3) if (nS .gt. 1) n5 = n5+Lst(11,1)+Lst(11,2)+Lst(11,3) if ( n2+n3+n4+n5 .eq. 0) kF = HOS__F_1 if (n1 +n3+n4+n5 .eq. 0) kF = HOS__F_2 if (n1+n2 +n4+n5 .eq. 0) kF = HOS__F_3 if (n1+n2+n3 +n5 .eq. 0) kF = HOS__F_4 if (n1+n2+n3+n4 .eq. 0) kF = HOS__F_5 if (bOneFF(kF)) then iD = iD-iand(iD, HOS__F_ALL)+kF call Say(cSay,'W','Filters','Only one available: '//cInt2Str(kF)) end if end if end if return end