procedure standards (title)

string	title	=""		{prompt="object title"}
string	exp1	=""		{prompt="list of exposures in filter 1"}
string	exp2	=""		{prompt="list of exposures in filter 2"}
string	exp3	=""		{prompt="list of exposures in filter 3"}
string	exp4	=""		{prompt="list of exposures in filter 4"}
string	exp5	=""		{prompt="list of exposures in filter 5"}
string	exp6	=""		{prompt="list of exposures in filter 6"}
string	exp7	=""		{prompt="list of exposures in filter 7"}
string	exp8	=""		{prompt="list of exposures in filter 8"}
string	filt1	="2 1 1 0"	{prompt="wheel encoding, filter 1"}
string	filt2	="3 1 1 0"	{prompt="wheel encoding, filter 2"}
string	filt3	="4 1 1 0"	{prompt="wheel encoding, filter 3"}
string	filt4	="5 1 1 0"	{prompt="wheel encoding, filter 4"}
string	filt5	="1 2 1 0"	{prompt="wheel encoding, filter 5"}
string	filt6   ="1 3 1 0"	{prompt="wheel encoding, filter 6"}
string	filt7	="1 4 1 0"	{prompt="wheel encoding, filter 7"}
string	filt8	="1 5 1 0"	{prompt="wheel encoding, filter 8"}
string	filtnam	="U B V R I"	{prompt="space-separated filter names"}
bool	confirm	=yes		{prompt="confirm before taking next exposure?"}
bool	verbose	=yes		{prompt="print progress messages?"}
string	logfile	="obslog.txt"	{prompt="observing log file (optional)"}

# @(#) task standards                 Author: R.A. Jansen -- Apr  5 2005
# @(#) 
# @(#) Automatically cycle through (a subset of) at most 8 filters on an
# @(#) object or field at which the telescope is currently pointing, e.g
# @(#) a standard star field.  The 'exp1'--'exp8' parameters take either
# @(#) a single exposure time (in seconds), or a comma-separated list of
# @(#) exposure times. There is no limit on the number of exposures that
# @(#) may be requested per filter  (as long as  the 168-character limit
# @(#) for task parameter strings is not exceeded). If any of the 'exp1'
# @(#) through 'exp8'  are left blank,  then no exposures  will be taken
# @(#) through that filter.  Parameters 'filt1' -- 'filt8'  identify the
# @(#) filters corresponding to the specified exposure times, and can be
# @(#) used  to control the order  in which this task cycles through the
# @(#) filters (e.g., instead of the filter-wheel encoding for UBVRI one
# @(#) could specify those for UVIBR);  in particular,  the filter wheel
# @(#) encodings need not be unique (this allows sequences like UBVVBU).
# @(#) Note that the third column in the filter-wheel encoding specifies
# @(#) the filter for the Guide Camera (e.g., 1=clear, 5=red filter) and
# @(#) that the fourth column is not used at present (should be 0).
# @(#) Human-readable equivalents  to the filter-wheel encodings for the
# @(#) science filters given in 'filtnam'  are only used for error-  and
# @(#) informative messages.
# @(#) Typically,  one would use this task  for observations of standard
# @(#) star fields (hence its name),  but it could be equally well  used
# @(#) for observations of other science targets  that require exposures
# @(#) through more than one filter.  If conditions are photometric, one
# @(#) may change parameter 'confirm' from its failsafe default to 'no'.
# @(#) 
# @(#) Note that when the filters are under control of 'telpars' (called
# @(#) in this task through the 'observe' command), only the green field
# @(#) in the filter section of the TCS window indicates which filter is
# @(#) actually being used; the black radio button continues to indicate
# @(#) the last filter that was interactively selected by the observer.
# @(#) This might be considered a bug  (or feature, depending on whether
# @(#) such behavior is judged desirable) in the ICE/IRAF-TCS interface.
# @(#) 
# @(#) If not installed systemwide or in /home/vattobs/ already, one may
# @(#) get 'standards.cl' from http://www.public.asu.edu/~rjansen/vatt/
# @(#) and copy it to /home/vattobs/.
# @(#) 
# @(#) (1) Example of how to tell IRAF about this task's existence:
# @(#)   cl>  task standards = (path_to_task)/standards.cl
# @(#) where (path_to_task) could be, e.g., "/home/vattobs/"
# @(#) 
# @(#) (2) Example of how to cycle through U,B,V,R filters, with a short
# @(#) and long exposure per filter (we assume UBVR are in the top wheel
# @(#) in slots 2 through 5):
# @(#)   cl>  unlearn standards
# @(#)   cl>  standards "PG1047+003" exp1="30,90" exp2="20,60" \
# @(#)   >>>    exp3="15,45" exp4="10,30" filtnam="U B V R"
# @(#) 
# @(#) (3) Same example, but we loaded U,B,V,R in slots 5,3,2,4:
# @(#)   cl>  unlearn standards
# @(#)   cl>  standards.filt1="5 1 1 0"
# @(#)   cl>  standards.filt2="3 1 1 0"
# @(#)   cl>  standards.filt3="2 1 1 0"
# @(#)   cl>  standards.filt4="4 1 1 0"
# @(#)   cl>  standards.filtnam="U B V R"
# @(#) (the above could be done using 'eparam standards', just as well)
# @(#)   cl>  standards "PG1047+003" exp1="30,90" exp2="20,60" \
# @(#)   >>>    exp3="15,45" exp4="10,30"
# @(#) 
# @(#) (4) Example to cycle through BVR in a particular pattern, BVRRVB,
# @(#) with one exposure per filter and B,V,R filters loaded in the  top
# @(#) wheel in slots 2,3 and 4 (note, that the two R exposures could be
# @(#) specified in a single filter description):
# @(#)   cl>  standards.filt1="2 1 1 0"
# @(#)   cl>  standards.filt2="3 1 1 0"
# @(#)   cl>  standards.filt3="4 1 1 0"
# @(#)   cl>  standards.filt4=standards.filt2
# @(#)   cl>  standards.filt5=standards.filt1
# @(#)   cl>  standards.filtnam="B V R V B"
# @(#)   cl>  standards "PG1047+003" exp1=30 exp2=20 exp3="15,15" \
# @(#)   >>>    exp4=20 exp5=30
# @(#) 
# @(#) Revision history:
# @(#) Apr 8 2005 [RAJ] -- Added 'logfile' parameter and query of output
# @(#)                     image header per Chris Corbally's suggestion.
# @(#) 

begin
	string	objectname, filtername, cfilt[8], cexp[8], filt[8]
	string	badchar, cstr, sstr, tstr, cimg, cra, cstm, cutm, cha
	real	airm, rha
	int	i, j

	# Initialize variables...
	badchar = "abcdefghijklmnopqrstuvwxyz"
	badchar = badchar//"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
	badchar = badchar//"~!@#$%^&*()_-=:;><,?/\|[]{}`'"
	cexp[1] = exp1  ; cexp[2] = exp2  ; cexp[3] = exp3  ; cexp[4] = exp4
	cexp[5] = exp5  ; cexp[6] = exp6  ; cexp[7] = exp7  ; cexp[8] = exp8
	filt[1] = filt1 ; filt[2] = filt2 ; filt[3] = filt3 ; filt[4] = filt4
	filt[5] = filt5 ; filt[6] = filt6 ; filt[7] = filt7 ; filt[8] = filt8
	objectname = title
	filtername = filtnam//" - - - - - - - -"
	cstr = ""
	for ( i = 1 ; i <= 8 ; i = i + 1 ) {
	   print (filtername) | \
		fields("-", str(i), lines="1", quit-, print-) | scan(cfilt[i])
	   if ( cfilt[i] == "-" ) { cfilt[i] = "F"//str(i) }
	   cstr = cstr//cfilt[i]//" "
	}
	filtername = substr(cstr,1,strlen(cstr))
	telpars.telfocus=""

	# Opening message...
	if (verbose) {
	   printf("STANDARDS: object title = %s\n", objectname)
	   printf("           filternames  = %s\n\n", filtername)
	}
	# Open observing log file...
	if ( logfile != "" && logfile != " " ) {
	   if ( !access(logfile) ) {
	      print ("# ---------------- VATT CCD  Observing log ----------------", > logfile)
	      print ("#", >> logfile)
	      print ("# (automatically kept by 'standards' <Rolf.Jansen@asu.edu>)", >> logfile)
	      !echo -n "# " > .tmpdt ; date >> .tmpdt
	      !echo -n "# " >> .tmpdt ; date -u >> .tmpdt
	      type (".tmpdt", >> logfile)
	      delete (".tmpdt", yes, verify-)
	      print ("#", >> logfile)
	      print ("# nr   object       filt  Texp   UT    HA   airm   telfilte", >> logfile)
	      print ("#==========================================================", >> logfile)
	   }
	}

	# Cycle through all filters for which exposure times were specified...
	for ( i = 1 ; i <= 8 ; i = i + 1 ) {

	   telpars.telfilt = filt[i]

	   # Trim trailing decimal points (to catch case where both leading
	   # and trailing decimal points are inadvertenly typed):
	   if ( substr(cexp[i],strlen(cexp[i]),strlen(cexp[i])) == "." ) {
	      cexp[i] = substr(cexp[i],1,strlen(cexp[i])-1)
	   }

	   if ( cexp[i]=="" || cexp[i]==" " || cexp[i]=="0" || cexp[i]=="INDEF") {
	      # No exposure time specified for current filter; goto next one.
	      if (verbose) {
		 printf("\nNo exposures in filter '%s' requested.\n\n", cfilt[i])
	      }
	   } else {
	      # At least one exposure in the current filter was requested; if
	      # a comma-separated list of exposure times is provided, execute
	      # each in turn...
	      while ( cexp[i] != "" ) {

		 # Offer opportunity to wait before starting next exposure or
		 # to abort script alltogether:
		 if ( confirm ) {
		    cstr = ""
		    printf("\n---------------------------------------------------")
		    printf("\nHit <Return> when ready to proceed or 'q' to abort: ")
		    printf("\n---------------------------------------------------")
		    printf("\n") ; sleep 1 ; printf("")
		    if ( scan(cstr) != EOF ) {
		       if ( substr(cstr,1,1)=="q" || substr(cstr,1,1)=="Q" ) {
			  if (verbose) {
			     printf("\nSTANDARDS: All done.")
			     sleep 1 ; printf("")
			     sleep 1 ; printf("\n")
			  }
			  # reset to default state...
			  telpars.telfocus=""
			  telpars.telfilters=""
			  return
		       }
		    }
		 }

		 # Get current UT time (note: we escape to unix since iraf does
		 # not allow passing -u and format options to native task 'date'
		 !date -u +%T > .tmpdt
		 type (".tmpdt") | scanf ("%s", tstr)
		 delete (".tmpdt", yes, verify-)

		 # j=0 means that only a single exposure time was specified:
		 j = stridx(",", cexp[i])

		 # construct image root name...
		 printf("%s%04d\n", obspars.rootname, obspars.sequence) | scan (cimg)

		 if ( j == 0 ) {

		    # make sure typos are caught: only 0-9.+ are valid chars:
		    if ( stridx(badchar,cexp[i]) > 0 ) {
		       error(1, "invalid character in exposure time(s) for filter '//cfilt[i]//'!")
		    }
		    if (verbose) {
		       printf("\n%s %-13s %-5s %4d %5.5h\n", cimg, objectname,
				cfilt[i], real(cexp[i]), tstr)
		    }

		    # execute observation...
		    observe (imagetype="object", exposuretime=real(cexp[i]),
			objecttitle=objectname)

		    # retrieve information for observing log from header...
		    if ( logfile != "" && logfile != " " ) {
		       hselect (cimg, "ra", yes) | scan (cra)
		       hselect (cimg, "st", yes) | scan (cstm)
		       hselect (cimg, "ut", yes) | scan (cutm)
		       hselect (cimg, "airmass", yes) | scan (airm)
		       rha = (real(cstm)-real(cra))
		       if ( abs(rha) == rha ) {
		          printf("+%9h\n", rha) | scan (cha)
		       } else {
			  printf("-%9h\n", abs(rha)) | scan (cha)
		       }
		       printf("%s %-13s %-5s %4d %5.5h %5s %5.3f  [%s]\n", cimg,
				objectname, cfilt[i], real(cexp[i]), cutm, 
				substr(cha,1,5), airm, filt[i], >> logfile)
		    }

		    cexp[i] = ""

		 } else {
		    sstr = substr(cexp[i],1,j-1)

		    # make sure typos are caught: only 0-9.+ are valid chars:
		    if ( stridx(badchar,sstr) > 0 ) {
		       error(1, "invalid character in exposure time(s) for filter '//cfilt[i]//'!")
		    }
		    if (verbose) {
		       printf("\n%s %-13s %-5s %4d %5.5h\n", cimg, objectname,
				cfilt[i], real(sstr), tstr)
		    }

		    # execute observation...
		    observe (imagetype="object", exposuretime=real(sstr),
			objecttitle=objectname)

		    # retrieve information for observing log from header...
		    if ( logfile != "" && logfile != " " ) {
		       hselect (cimg, "ra", yes) | scan (cra)
		       hselect (cimg, "st", yes) | scan (cstm)
		       hselect (cimg, "ut", yes) | scan (cutm)
		       hselect (cimg, "airmass", yes) | scan (airm)
		       rha = (real(cstm)-real(cra))
		       if ( abs(rha) == rha ) {
		          printf("+%9h\n", rha) | scan (cha)
		       } else {
			  printf("-%9h\n", abs(rha)) | scan (cha)
		       }
		       printf("%s %-13s %-5s %4d %5.5h %5s %5.3f  [%s]\n",
				cimg, objectname, cfilt[i], real(sstr), cutm, 
				substr(cha,1,5), airm, filt[i], >> logfile)
		    }

		    cstr = substr(cexp[i],j+1,strlen(cexp[i]))
		    cexp[i] = cstr

		 }
	      }
	   }
	}

	# reset to default state...
	telpars.telfocus=""
	telpars.telfilters=""

	if (verbose) {
	   printf("\nSTANDARDS: All done.")
	   sleep 1 ; printf("")
	   sleep 1 ; printf("\n")
	}

end