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,
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;
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
TRG may contain additional options after the ]-delimiter ________________. |
/ \ / \
',Rwd' - rewind the file before processing. TRG FMT
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
- seconds from epoch 2000.0 (1999-12-31 12:00)
and shift by s seconds.
',SEC:' - ... assume s=0.
- years are coded by tens and ones only. Years less
...................than v are interpreted as after 2000 and years
greater or equal v are treated between 1900 and 2000
- Round start time to integer v hours
(h), minutes (m)
or seconds (s) TRG FMT
and shift by s seconds.
',UXS:' - ... assume s=0.
',Fh=h' - fix origin time at this hour. TRG FMT
- will set (override!) the sampling interval.
primarily with SD:
- Time offset for read_fm_doff (toff)
is added to the time values input, in hours.
- "Until", read up to and including this date
- accumulative extension of ending time
- File has no date record (year,month,day). Supply
the first one here.
Date formats (we only allow year-month-day, in that order
',DF:code' - Date format code; avoid `( )´ ['I2,I4,I3'] FMT
- Hour record is a floating point
Input values are divided by scale s and
.................offset by add
',DH+/add,s' - take reciprocal value for s.
',DBG+' ' DBG-'
- debug switch on /
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)
For debugging some records but not the initial stage,
specify e.g. DBG-,DBG:10,19
- Doubt-margin for read_fm_doubt (dv)
',M>0' - Convert MRS's to zero FMT
- "Over"; records pointing to the same time: Admit the
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
- Stop reading if text appears at
',EOFT:text]' - (uses the eof_by_target feature, unclear what it does.)
- Stop after error count;
date and format problems
',#SE=count' - Stop after error count; target storage violations FMT
- 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
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.
setenv MYLABEL 'BARO|VAL'
setenv MYENDING 2013,11,05
to set actual replacments
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
Table 2. Read procedures, actual call
parameters, and applicable options:
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
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!'
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,
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
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.
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.