SAS utility * Switchboard of read routines. Source file: ~/sas/p/ufios.f

     subroutine read_fuf (iun,trg,rec_mrs,r,n,nr,nsk,fmt,khms,itz,t0,dt)

 Read formatted or unformatted, a hub-and-spokes procedure for calling one of four reading routines,

 TRG(:3)='BIN' - call GETTS,                     single- or multi-component (labeled) binary data.
        ='BRX' - call Read_Brx (iun,TRG(5:),...) ASCII data 
 TRG=other     - call Read_Fm_D if KHMS >= 0     ASCII data with kalendar dates
                      Read_Fm   if KHMS  < 0     ASCII data, undated

 With TRG(1:3)='BIN', format fmt(1:1) must be ' ' or 'L' or 'U'

 Location of read start by TRG takes place in Read_Fm_D; underscore characters
 in TRG are replaced by whitespaces; the first occurrence of TRG(:L)
 (where L is INDEX(TRG,']')-1) without backspace is used.
 If this method implies limitation, use QLOC_IN_FILE ( util/afor/p/qlocf.f) instead,
 and set TRG='TOP'

 The Format string will be analyzed by Read_FM_D to detect the date record
 type. C.f. ~/sas/p/readfmd.f
 

 Table 1. Additional options that can be passed via TRG or FMT
 _______________________________________________________________________________

 FMT may contain additional options after the closing parenthesis )___________.
 TRG may contain additional options after the ]-delimiter ________________.   |
                                                                          |   |
                                                                         / \ / \
 ',Rwd'          - rewind the file before processing.                    TRG FMT

 ',Y:year'     - Floating point date records are decimal years.
                   Fix at specified year, Jan 1 (Read_FM_D only).        TRG FMT

 ' J:O' ' J:I'   - Floating point date records are Julian days.
.................:O - Official definition of Julian date (new day
                       starts at noon)
.................:I - Inofficial, new day starts at midnight.        
Uncertain how/whether this still works

Time records are ...

 ',RJD: MJD: XJD:O XJD:I'   - reduced, modified or full Julian           TRG FMT

 ',SEC+s:'       - seconds from epoch 2000.0 (1999-12-31 12:00)          TRG FMT
                   and shift by s seconds.
 ',SEC:'         - ... assume s=0.

 ',Y2K[:v]'    - years are coded by tens and ones only. Years less         FMT
...................than v are interpreted as after 2000 and years
                   greater or equal v are treated between 1900 and 2000

 ',R{h|m|s}:v'   - Round start time to integer v hours (h), minutes (m)
                   or seconds (s)
                                        TRG FMT

 ',UXS+s'        - seconds from UNIX epoch 1970 (1970 01 01 00:00)       TRG FMT

                   and shift by s seconds.
 ',UXS:'         - ... assume s=0.

 ',Fh=h'         - fix origin time at this hour.                         TRG FMT

 ',DT=dt'        - will set (override!) the sampling interval. Useful
                   primarily with SD:

 ',T+off'        - Time offset for read_fm_doff (toff)                       FMT
                   is added to the time values input, in hours.

 ',UNT=yyyy,mm,dd[,hh[,mm[,ss[,fff]]]]:'
                 - "Until", read up to and including this date

 ',EXT+days[,hours[,seconds]]:'
                 - accumulative extension of ending time

 ',SD=date:'     - File has no date record (year,month,day). Supply          FMT
                   the first one here.

Date formats (we only allow year-month-day, in that order though):

 ',DF:code'      - Date format code; avoid `( )´          ['I2,I4,I3']       FMT

 ',DH+add,s'     - Hour record is a floating point number.                   FMT
                   Input values are divided by scale s and
 
.................offset by add
 ',DH+/add,s'    - take reciprocal value for s.

 ',DBG+' ' DBG-' - debug switch on / off                                     FMT
                   read_fm_d produces excessive debug output!
 ',DBG:beg,end
'  - Record numbers that set debug on and off.                 FMT
                      end =  1 will stop debugging at once
                      end = -1 will debug indefinitely.
                   For debugging the initial stage of
                      read_fuf and read_fm_d (disband during file reading)
                      specify DBG+,DBG:0,1
                  
For debugging some records but not the initial stage,
                      specify e.g. DBG-,DBG:10,19

 ',Dm=dv'        - Doubt-margin for read_fm_doubt (dv)                       FMT

Other:

 ',EPS=eps'    - A small rounding constant for floating point data.          FMT
                   If eps<-0.5, 10**eps will be used.

                   Applies to Julian (and whenever IHMS(1..4) is

                  
computed from HHMS; see the source code, search for
                   `epsilon´ in readfmd.f, sorry for that)    [0.5D-8]

 ',M>0'          - Convert MRS's to zero                                     FMT

 ',O-'           - "Over"; records pointing to the same time: Admit the      FMT
                   one that appears first. Default is last. 'O+' to reset.
 ',IUX=n       - With O+ : Instead of admitting, copy the respective input
                   records to the file /tmp/readfmd.xcp using file unit n.   FMT

 ',WO:text]'     - weed out records containing this text                     FMT
 
',WOX:text@p]'  - weed out records containing this text at position p       FMT
                   WO: and WOX: can be repeated; in total max. 10 times.

 ',EOF:text]'    - Stop reading if text appears at position 1                FMT
 ',EOFT:text]'   - (uses the eof_by_target feature, unclear what it does.)

 ',#E=count'     - Stop after error count; date and format problems          FMT
 ',#SE=count'    - Stop after error count; target storage violations         FMT

 'L:label'       - for binary multi-component files: specify label.
                   Must be combined with TRG='BIN'.
                   Code as TRG='BIN,L:label '
                        or TRG='BIN]L:label '
                        or TRG='BIN' FMT='L:label '
                   'L:' must start in position one of FMT string         TRG FMT

Environment:
The string beyond the format code (beyond the last ')' else the beginning) is processed for
replacement of environment variables. (Why not all ?!) The main use for this is to enable flexible location
of segments in multicomponent files using the label option. You can specify e.g. 

  'L:${MYLABEL:[GRAV|VAL]} '
or
  '(i4,3i3,t38,f10.0) ${MYENDING}'

and use
  setenv MYLABEL 'BARO|VAL'
  setenv MYENDING 2013,11,05
to set actual replacments

Coding labels:
Labels consist usually of two parts, a station part and a component part.
Match is with starting pieces of strings separated by  '|'. For instance the label
'LAMPEDUSA___RAD' can be matched with  'L|R' if it's the only label starting
with  'L' and all other components at  'LAMPEDUSA' have codes that start with
different letters than 'R'. Instead of  `|´ you may use `+´.
To find the labels of an MC-file, consider

  tslist file.mc -L | fgrep '<Loc'
 

_________________________________________________________________________________

 Table 2. Read procedures, actual call parameters, and applicable options:
                _SAC
Proc:    GETTS |   _BRX _FM  _FM_D
           \   |  |    /    / 
            |  |  |   |    /  i-input
            |  |  |   |   |   o-output
            |  |  |   |   |   |
Parameter   |  |  |   |   |   |  type
----------------------------------------------------------------------------
iun         Y  Y  Y   Y   Y   i integer - file unit
trg         B  S  E   Y   Y+  i char**  - start mark, right-delim.: ]
                                          B: mode switch trg='BIN' or
                                             trg(1:4)='BIN]'
                                          S: mode switch trg='SAC'
                                          E: mode switch 'BRX'//eof-mark//']'
                                        
rec_mrs     T  -  Y   Y   Y   i real*8  - miss.record symb.value
                                          T: used only if trg contains 'M!'
                                             after 'BIN]'
r(0:n-1)    Y  Y  Y   Y   Y   o real*8  - array, n=calling pgm's dimension
nr          Y  Y  Y   Y   Y   o integer - returned data length
nsk         Y  0  Y   Y   Y   o integer - time of R(NSK) within DT from epoch
fmt         L  -  X   Y   Y+  i char**  - format
                                          X: numeriformat substring.
                                          L: Location string for mc-files,
                                             cf.  Loc_Getts_Mbelow.
                                             fmt(1:2) = 'l:' or 'L:' or '*:'
                                             selects MC-file mode. Must be
                                             combined with trg='BIN'
khms        -  -  -  <0   Y   i integer - 1..3: test on HH MM SS
itz         Y  -  -   -   Y   i integer - data is in time zone ITZ
t0          Y  Y  Y   I   Y   o real*8  - time of R(0) after epoch [h]
dt          Y  Y  Y   I   Y   o real*8  - sampling interval [h]

                                         +: additional options see Table 1

___________________________________________________________________________________

Coding Fortran:
 Call Set_Epoch (or other routines that set the epoch in /CTIME/) in order set
 the reference for t0

 Call Get_A_Name (Name*64) to receive
 (1) the section name (16 significant characters) of mc-file
 (2) the file name otherwise.

Additional remarks
dt - real*8 - If a number > 0 is supplied, the system will use this as the
              sampling interval. Else it will try to determine dt from the file.

t0 - real*8 - A number different from 0 can be supplied to offset the time
              of the first sample, but use of this option is discouraged.