; docformat = 'rst'
;
; NAME: 
;    readAstDysPair
; PURPOSE:
;    Read the list of paired asteroids from AstDys
;
;+
; :Description:
;    Read the list of paired asteroids from AstDys
;
; :Categories:
;    Database, Asteroid
;    
; :Params:
;    file: in, required, type=string
;        Path to a local version of the AstDys pair file
;
; :Keywords:
;
; :Returns: A structure with the orbital elements and the absolute
;           magnitude. Fields are::
;      .Ast1: First asteroid structure:
;         .num: IAU Number
;         .H  : Absolute magnitude
;      .Ast2: Second asteroid structure:
;         .num: IAU Number
;         .H  : Absolute magnitude
;      .sigma: Distance between asteroids
;      .dA: Difference in Semi-major axis (au)
;      .dE: Difference in Eccentricity
;      .dI: Difference in sin(Inclination)
;  
; :Examples:
;    Read the whole list of pairs::
;        IDL> pairs = readAstDysPairs('LOCAL_FILE')
;
; :Uses:
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;     Change History::
;        Written in October 2015, B. Carry (OCA)
;-
function readAstDysPairs, file

;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
  COMPILE_OPT hidden, idl2

 ;--I.1-- Test Input AstDys Pair File  --------------------------------------------------
  if not keyword_Set(file) then begin
    message, /IOERROR, 'Syntax error: pair = readAstDysPair( FILE )'
    return, -1
  endif


 ;--I.2-- Test if File Exist  -----------------------------------------------------------
  if not file_test(file,/read) then begin
    message, /IOERROR, 'AstDys pair file not found: '+file
    return, -2
  endif

 ;--I.3-- Output Structure  -------------------------------------------------------------
  emptyAst={num:0L, H:0.}
  empty={ ast1:emptyAst, ast2:emptyAst, sigma:0., da:0.d, de:0., di:0.}



;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Read AstDys File                                   -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--II.1-- Blind Read Out  ---------------------------------------------------------------
  readcol, file, n1, h1, n2, h2, sigma, da, de, di, format='(L,F,L,F,F,F,F)', /silent
  nbPair = n_elements(n1)

 ;--II.2-- Store in Structure  -----------------------------------------------------------
  pair = replicate(empty, nbPair)
  pair.ast1.num = n1
  pair.ast1.H   = h1
  pair.ast2.num = n2
  pair.ast2.H   = h2
  pair.sigma    = sigma
  pair.da       = da
  pair.de       = de
  pair.di       = di

 ;--II.3-- Return Pair Structure  --------------------------------------------------------
  return, pair

end