; docformat = 'rst'
;
; NAME:
;    genoidMergeObs
; PURPOSE:
;    Merge several Genoid VOTable into one, with possible sorting of entrie
;
;+
; :Description:
;    Merge several Genoid VOTable into one, with possible sorting of entrie
;
; :Categories:
;    Disk I/O, Genoid
;    
; :Params:
;    in: in, required, type=string
;        A list of paths to the individual XML files
;    dump: in, required, type=string
;        The path to the merged XML file
;
; :Keywords:
;    sort: in, optional, type=boolean, default=0
;        If set, the entries in the final file will be sorted by date
;
; :Uses:
;    genoidOpenObs, genoidAddObs, genoidCloseObs
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;    Change History::
;      Written in July 2013, B. Carry (IMCCE)
;      2013 Sep. - B.Carry (IMCCE) - Cleaned
;      2014 Jun. - B.Carry (IMCCE) - Verification of inputs added
;      2017 Apr. - B.Carry (OCA) - Update to new Genoid format & functions
;-
pro genoidMergeObs, in, dump, sort=sort
  COMPILE_OPT hidden, idl2
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--I.1-- Syntax Validation  -------------------------------------------------------------------;
  if N_PARAMS() lt 2 then begin
    message, /ioError, 'Syntax : genoidMergeObs, in, dump  [,/sort]'
    return
  endif


 ;--I.2-- Check All Input VOTables  ------------------------------------------------------------;
  nbFile=n_elements(in)
  goOut=0
  for kFile=0, nbFile-1 do begin
    if not file_test(in[kFile],/Read) then begin
      goOut=1
      message, /INFO, 'Input XML file not found: '+strTrim(in[kFile],2)
    endif
  endfor
  if goOut eq 1 then stop

 ;--I.3-- Output Structure  --------------------------------------------------------------------;
  maxEp = 1000
  xyEmpty={obs:0., err:0., cal:0., omc:0.}
  sat = replicate( {jd: 0.0d, iso: '', $
                    refName: '', refSys: '', $
                    x: xyEmpty, y: xyEmpty, $
                    timeScale: '', centerFrame: 0., typeFrame: 0., $
                    coordType: 0., refFrame: 0., iau:'', $
                    method: '', Mag:0., dMag:0., $
                    QC: '', telescope:'', camera:'', filter:'', author:'', $
                    when: '', bib: ''}, maxEp )


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Read Individual Input XML Files                    -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--II.1-- Loop over Files  --------------------------------------------------------------------;
  kEp=0
  for kFile=0, nbFile-1 do begin

   ;--II.2-- Read Current File  ----------------------------------------------------------------;
    curSat = genoidReadObs( in[kFile] )
    nbCur = n_elements(curSat)

   ;--II.3-- Store Observations from Current XML to Output Structure  --------------------------;
    for kCur=0, nbCur-1 do begin
      sat[kEp] = curSat[kCur]
      kEp++
    endfor

  endfor


 ;--II.4-- Trim Output Structure  --------------------------------------------------------------;
  nbEp = kEp
  sat=sat[0:nbEp-1]



;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---  III -- Sort and Export                                    -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--III.1-- Sort Entries by Date if Requested  -------------------------------------------------;
  if keyword_set( sort ) then begin
    order = sort( sat[*].jd )
    sat = sat[order]
  endif

 ;--III.2-- Write Merged Genoid Structure to Disk  --------------------------------------------;
  unit = genoidOpenObs( dump, nbEp )
  genoidAddObs, unit, sat
  genoidCloseObs, unit

end