;+
;
; =====================
; file_asc_long2mem.pro
; =====================
;
; .. function:: file_asc_long2mem(filename)
;
;    Read long station information files and store data in a structure
;
;    :param filename: filename to be read
;    :type filename: string
;    :raise filename: required
;
;    :returns: data structure +todo+ details or -1 if error
;    :rtype: structure +todo+ details
;
; notes
; 18 fields in header vs 19 data fields. missing mm of ending time
;
; :examples:
;
; .. code-block:: idl
;
;    filename='/usr/work/incas/fplod/pomme_d/sta.P1L2.asc'
;    result = file_asc_long2mem(filename)
;
; impression de contrôle : structure, 1re station, toutes les stations :
;
; .. code-block:: idl
;
;    print, result, /structure
;    print, result[0].station
;    print, result.station
;
; :uses:
;
; :func:`report <saxo:report>`
;
; :restrictions:
;
; :todo:
;
; format fixe
;
; test existence of filename
;
; :history:
;
; - fplod 20110426T152245Z cratos.locean-ipsl.upmc.fr (Linux)
;
;   * usage of PROJECT
;
; - fplod 20101123T122132Z aedon.locean-ipsl.upmc.fr (Darwin)
;
;   * creation using "Reading Into a Structure" of
;     http://www.dfanning.com/tips/ascii_column_data.html
;
; :version:
;
; $Id$
;
;-
FUNCTION file_asc_long2mem, filename
    ;
    compile_opt idl2, strictarrsubs
    ;
    ; Return to caller if errors
    ON_ERROR, 2
    ;
    usage = 'result = file_asc_long2mem(filename)'
    ;
    nparam = N_PARAMS()
    IF (nparam LT 1) THEN BEGIN
        ras = report(['Incorrect number of arguments.' $
        + '!C' $
        + 'Usage : ' + usage])
        return, -1
    ENDIF
    ;
    arg_type = size(filename,/type)
    IF (arg_type NE 7) THEN BEGIN
        ras = report(['Incorrect arg type filename' $
        + '!C' $
        + 'Usage : ' + usage])
        return, -1
    ENDIF
    ;
    arg_dim =  size(filename,/n_elements)
    IF (arg_dim LT 1) THEN BEGIN
        ras = report(['Incorrect arg dimension filename' $
        + '!C' $
        + 'Usage : ' + usage])
        return, -1
    ENDIF
    ;
    ; initialize header
    header = STRARR(1)
    ;
    resultstruct = { station: 0L $
    , sonde: 0L $
    , zmax: 0L $
    , an: 0L $
    , mm: 0L $
    , jj: 0L $
    , hh_begin: 0L $
    , mm_begin: 0L $
    , ss: 0L $
    , deg_lat_begin : 0L $
    , mm_lat_begin: 0.0 $
    , deg_lon_begin: 0L $
    , mm_lon_begin: 0.0 $
    , deg_lat_end: 0L $
    , mm_lat_end: 0.0 $
    , deg_lon_end: 0L $
    , mm_lon_end: 0.0 $
    , hh_end: 0L $
    , mm_end: 0L }
    ;
    nrows = file_lines(filename) - N_ELEMENTS(header)
    result = Replicate(resultstruct, nrows)
    ;
    ; open file
    OPENR, lun, filename, /GET_LUN
    ;++ handle error
    ;
    ; read header
    READF, lun, header
    ;
    ; read data lines
    READF, lun, result
    ;
    ; close file
    FREE_LUN, lun
    ;
    return, result
    ;
END