;---------------------------------------------------------------------------
; Document name: UTC_HEAD.PRO
; Created by:    Dietmar Germerott, MPAE Lindau, March 4, 1997
;
; Last Modified: Thu May 10 11:57:28 2007 (GERMEROTT.nospam(at)linmpi.mpg.de)
;---------------------------------------------------------------------------
;
FUNCTION UTC_HEAD, header, EXTERNAL=EXTERNAL, CCSDS=CCSDS, ECS=ECS, $
                   vms=vms, stime=stime, truncate=truncate, date_only=date_only, $
                   time_only=time_only, uppercase=uppercase, errmsg=errmsg
   
;+
; PROJECT:
;       SOHO - SUMER
;
; NAME:
;       UTC_HEAD()
;
; PURPOSE: 
;       Calculates the UTC_HEAD when the integration of a SUMER image started
;
; CATEGORY:
;       RAW processing
; 
; EXPLANATION:
;       
; SYNTAX: 
;       Result = utc_head(header[,/EXTERNAL,/CCSDS,/ECS])
;
; EXAMPLES:
;       
; INPUTS:
;       header - 92..,n Byte ARRAY SUMER binary header
;
; OPTIONAL INPUTS: 
;       None.
;
; OUTPUTS:
;       struct or string Array of dimension n
;       The result of the function will be the UTC calendar time in one
;		of several formats, depending on the keywords passed.
;
;			Internal:  A structure containing the tags:
;
;				MJD:	The Modified Julian Day number.
;				TIME:	The time of day, in milliseconds since
;					the beginning of the day.
;
;				   Both are long integers.  This is the default
;				   format.
;
;			External:  A structure containing the integer tags
;				   YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and
;				   MILLISECOND.
;
;			CCSDS:	   An ASCII string containing the UTC time to
;				   millisecond accuracy in the format
;				   recommended by the Consultative Committee
;				   for Space Data Systems (ISO 8601), e.g.
;
;					"1988-01-18T17:20:43.123Z"
;
;			ECS:	   Similar to CCSDS, except that the date has
;				   the format:
;
;					"1988/01/18 17:20:43.123"
;
;			VMS:	   The date and time has the format
;
;					"18-JAN-1988 17:20:43.123"
;
;			STIME:	   The date and time has the format
;
;					"18-JAN-1988 17:20:43.12"
;
;				   See UTC2STR for more information.
;
; Opt. Outputs:	None.
;
; Keywords    :	EXTERNAL = If set, then the output is in external format, as
;			   explained above.
;
;		CCSDS	 = If set, then the output is in CCSDS format, as
;			   explained above.
;
;		ECS	 = If set, then the output is in ECS format, as
;			   explained above.
;
;		VMS	 = If set, then the output will be in VMS format, as
;			   described above.
;
;		STIME	 = If set, then the output will be in STIME format, as
;			   described above.
;
;		The following keywords are only valid if one of the string
;		formats is selected.
;
;		TRUNCATE  = If set, then the time will be truncated to 1 second
;			    accuracy.  Note that this is not the same thing as
;			    rounding off to the nearest second, but is a
;			    rounding down.
;
;		DATE_ONLY = If set, then only the date part of the string is
;			    returned.
;
;		TIME_ONLY = If set, then only the time part of the string is
;			    returned.
;
;		UPPERCASE = If set, then the month field in either the VMS or
;			    STIME format is returned as uppercase.
;
;		The following keyword is always valid.
;
;		ERRMSG	 = If defined and passed, then any error messages 
;			   will be returned to the user in this parameter 
;			   rather than being handled by the IDL MESSAGE 
;			   utility.  If no errors are encountered, then a null 
;			   string is returned.  In order to use this feature, 
;			   the string ERRMSG must be defined first, e.g.,
;
;				ERRMSG = ''
;				RESULT = UTC_HEAD( head, ERRMSG=ERRMSG )
;				IF ERRMSG NE '' THEN ...
;
;
; COMMON:
;       None.
;
; RESTRICTIONS: 
;       Calls OBT2TAI, TAI2UTC
;
; SIDE EFFECTS:
;       None.
;
; HISTORY:
;       Version 1, March 4, 1997, Dietmar Germerott, MPAE Lindau. Written
;       UTC_HEAD.PRO uses routines programmed by W.Thompson (GSFC)
;       September 23, 1996 Georg Tomasch    
;       Version 2.0, June 20, 1997, Dietmar Germerott, MPAE Lindau
;       changed name to utc_head because of name conflict
;       Version 3, May 10, 2007, Dietmar Germerott, MPAE Lindau
;          added check for header size. if header size is below 92 byte
;          it is assumed thet only the 6 byte for header time are present
;
; CONTACT:
;       Dietmar Germerott, MPAE Lindau (germerott@linax1.mpae.gwdg.de)
;-
;
  
   IF (SIZE(header))(1) GE 92 THEN t = header(4:9, *) ELSE t = header
   RETURN, TAI2UTC(OBT2TAI(t), EXTERNAL=EXTERNAL, CCSDS=CCSDS, ECS=ECS, $
                   vms=vms, stime=stime, truncate=truncate, date_only=date_only, $
                   time_only=time_only, uppercase=uppercase, errmsg=errmsg)

END

;---------------------------------------------------------------------------
; End of 'UTC_HEAD.PRO'.
;---------------------------------------------------------------------------