;----------------------------------------------------------------------------
; $Id: julday_to_ymdh.pro,v 1.4 2002/09/09 22:48:28 johnny Exp $
;+
; NAME:
;   JULDAY_TO_YMDH
;
; PURPOSE:
;   Given Julian Day, convert to Year/Month/Day/Hour long integer.  This 
;   integer can be expressed as either 4-digit year (yyyymmddhh, which
;   is the default) or 2-digit year (yymmddhh).  Year must be between
;   1000 and 9999, inclusive.  Hour is calculated using the conventions
;   in CALDAT.
;
;   Note:  This function is not an exact inverse of YMDH_TO_JULDAY since
;   this function can output 2-digit years and has an option to round
;   up minute 59 to the nearest hour.
;
; CATEGORY:
;   Date and Time.
;
; CALLING SEQUENCE:
;   Result = JULDAY_TO_YMDH(in_jday)
;
; INPUTS:
;   in_jday:       Julian Day (double precision float).  Scalar or array.
;                  Variable unchanged by routine.
;
; KEYWORD PARAMETERS:
;   MIN59:         If keyword is set true, for times where CALDAT calcu-
;                  lates the minute field of the Julian Day is 59, the 
;                  calculation is redone with two extra minutes added 
;                  forcing the time to be rounded up to the next hour.
;                  This is to get around precision problems with CALDAT
;                  when input hourly data is of a type that does not
;                  carry full double precision information.
;
;   YYOUT:         If keyword is set true, the year field is truncated to
;                  two digits for output.
;
; OUTPUTS:
;   Result:        Date as Year/Month/Day/Hour long integer.  Same dimen-
;                  sions as in_jday.  Created by function.
;
; FILE DEVICE I/O:
;   None.
;
; COMMON BLOCKS:
;   None.
;
; EXAMPLE:
;   Enter in a simple data sequence, run routine, and print results:
;       jday = JULDAY(12, 2, 1998, 3, 0)
;       ymdh = JULDAY_TO_YMDH(jday)
;       PRINT, ymdh
;   IDL prints:
;       1998120203
;
; MODIFICATION HISTORY:
; - 14 Mar 2002:  Orig. ver. Johnny Lin, CIRES/University of Colorado.
;   Email:  air_jlin@yahoo.com.  Passed moderately adequate tests.
; - 9 Sep 2002:  Added keyword to round-up minute 59 cases.  Passed
;   reasonably passable tests.
;
; NOTES:
; - Written for IDL 5.5.
; - All keyword parameters are optional unless otherwise stated.
; - No procedures called with _Extra keyword invoked.
; - No user-written procedures called.
;-
; Copyright (c) 2002 Johnny Lin.  For licensing, distribution conditions,
; and contact information, see http://www.johnny-lin.com/lib.html.
;----------------------------------------------------------------------------

FUNCTION JULDAY_TO_YMDH, in_jday  $
                       , MIN59  = min59  $
                       , YYOUT  = yyout  $
                       , _EXTRA = extra




; -------------------- Error Check and Parameter Setting --------------------

COMPILE_OPT IDL2
ON_ERROR, 0

jday = in_jday                               ;- protect input variable

if (SIZE(jday, /Type) ne 5) then  $          ;- error check
   MESSAGE, 'error--input must be double'




; ------------------------ Find Year/Month/Day/Hour -------------------------

CALDAT, jday, mo, dy, yr, hr, min, sec                ;- convert Julian to
                                                      ;  yr, mo, etc.

if (KEYWORD_SET(min59) eq 1) then begin               ;- add 2 extra min.
   two_min   = 2.d0/24.d0/60.d0                       ;  to places where
   min59_pts = WHERE(min eq 59, count)                ;  min eq 59 (optional)
   if (count gt 0) then begin
      jday[min59_pts] = jday[min59_pts] + two_min
      CALDAT, jday, mo, dy, yr, hr, min, sec
   endif
endif

max_yr = MAX(yr, Min=min_yr)                          ;- error check year
if ((max_yr gt 9999) or (min_yr lt 1000)) then  $     ;  to be in range
   MESSAGE, 'error--yr outside of range'

if (KEYWORD_SET(yyout) eq 1) then begin               ;- case to display yr
   yr = yr - ((yr/100)*100)                           ;  as 2-digit value
endif

ymdh = (TEMPORARY(yr)*1000000)  $                     ;- concat. as integer
     + (TEMPORARY(mo)*10000)  $
     + (TEMPORARY(dy)*100)  $
     +  TEMPORARY(hr)




; ----------------------------- Prepare Output ------------------------------

Result = TEMPORARY(ymdh)         ;- return ymdh

RETURN, Result




END     ;=== end of function ===

; ========== end file ==========