;+
; Project     : SOHO - CDS     
;                   
; Name        : CDS_UTSTRING
;               
; Purpose     : To overprint a string on a UTPLOT graph
;               
; Explanation : Converts input x-variable to seconds, applies the time offset
;               stored in common and overprints data on a plot created by
;               UTPLOT.
;               
; Use         : IDL> cds_utstring, x, y, string
;    
; Inputs      : x - the time location.  May be either an array of CDS internal
;                                       time structures (as produced by the 
;                                       routine STR2UTC, say) or...
; 
;                                       a string array of date/times in a 
;                                       format translatable by STR2UTC.
;
;               y - the data value location of the text
;
;               string - the string to print on the plot
;               
; Opt. Inputs : Various keywords.
;               
; Outputs     : None
;               
; Opt. Outputs: None
;               
; Keywords    : dmy         - if the x-variable is a list of date/time strings
;                             this keyword must be used if they are in the
;                             format dd-mm(m)-yyyy as opposed to the CDS 
;                             'official' format of yyyy-mm-dd
;
;               charsize    - usual character size parameter
;               orientation - usual character orientation parameter
;
;
; Calls       : STR2UTC
;               UTC2SEC
;               SEC2UTC
;               VCHECK
;
;
; Common      : cds_utplot_com  (for passing of time axis offset to outplot)
;               
; Restrictions: Any 2-character year specifications are translated as being
;               between 1950 and 2049 (use 4-characters as necessary).
;
;               
; Side effects: None
;               
; Category    : Data display, plotting
;               
; Prev. Hist. : None
;       
;
; Written     : C D Pike, RAL, 3-Feb-95
;               
; Modified    : Name change.  CDP, 2-Oct-96
;
; Version     : Version 2, 2-Oct-96
;-            

pro cds_utstring, x_in, y, str, charsize=charsize, orientation=orientation


;
;  common for offset value passed from utplot
;
common cds_utplot_com, cds_xoffset

;
;  tidy up on error
;
on_error,2


;
;  validate input
;
;
;  either CDS internal time structure or array of date/time strings
;
case datatype(x_in,1) of
   'Structure': x = x_in
   'String'   : begin
                   if keyword_set(dmy) then begin
                      x = str2utc(x_in,/dmy)
                   endif else begin
                      x = str2utc(x_in)
                   endelse
                end
    else      : begin 
                   print,' '
                   print,'OUTPLOT: x-variable must be either:'
                   print,'1) an array of CDS internal time structures.
                   print,'  or ...'
                   print,'2) an array of CDS date/time strings.'
                   print,' '
                   return
                end
endcase
;
;  save current settings
;
psave = !p
        !p.channel=vcheck(channel,!p.channel)
        !p.clip=vcheck(clip,!p.clip)
        !p.color=vcheck(color,!p.color)
        !p.linestyle=vcheck(linestyle,!p.linestyle)
        !p.noclip=vcheck(noclip,!p.noclip)
        !p.nsum=vcheck(nsum,!p.nsum)
        !p.psym=vcheck(psym,!p.psym)
        !p.t3d=vcheck(t3d,!p.t3d)
        !p.thick=vcheck(thick,!p.thick)



;
;  perform the over printing using the defined !x variable
;
charsize = vcheck(charsize,1.0)
orientation = vcheck(orientation,0.0)

xyouts,utc2sec(x)-cds_xoffset, y, str, charsize=charsize,$
                                       orientation=orientation
;
;  restore setup
;
!p = psave

return
end