NAME
read_data -- read vector or image data from file
PROTOTYPE
unitptr read_data( char *pcFileName, char *pcFmtStr, unitptr uHost)
ARGUMENTS
- char *pcFileName
- input file
- char *pcFmtStr
- read format
- unitptr uHost
- host unit
RETURN VALUE:
A pointer to the created unit or NULL in the case of an error.
INTERFACE OF CREATED UNIT:
- CTL_in[3]:
- (control field) see below
- out_0..k:
- output fields as specified by the format string pcFmt
(see below)
- CTL_out[0]:
- (last output field) # of last record read
(records numbers start at 0 for the first record).
A value of -1 indicates that no record has been
fetched so far, or that the file is closed.
EXECUTION OF CREATED UNIT:
Each exec_unit call reads one record from file pcFileName and makes
the read data available at the output fields of the unit. Which data
are read and which output fields thus are created is specified with the
format string pcFmt (see below)
The order in which records are read can be determined by and
internal counter k and the
control field CTL_in.
Initially k is set to the value 0
If CTL[1]=CTL[2]=0 (compatibility mode with earlier versions):
k is simply incremented in steps of
CTL_in[0] and a new image [k] is fetched, whenever the
integral part [k] of k changes.
Otherwise: The first exec-call fetches record nr=[CTL_in[1]].
If the record is available, an internal counter k is set
to [CTL_in[1]] (otherwise a warning is issued and nothing is
changed). The internal counter k is then incremented by CTL_in[0].
Subsequent exec calls always return record [k] and increment
the internal counter according to k+=CTL_in[0] until the incremented
value reaches or exceeds the limit CTL_in[2]. If this happens,
k is reset to [CTL_in[1]] and the next exec call starts a new
cycle (Note that here [k] denotes the largest integer that is
not larger than k).
These rules allow simple reading of record sequences either
in arbitrary order (as specified by CTL_in[1], when CTL_in[2]<0
[note that CTL_in[2]=0 will not achieve this due to the simplified
incremental mode when CTL_in[1]=CTL_in[2]=0])
or in the cyclic fashion:
for (k=CTL_in[1]; k<CTL_in[2]; k += CTL_in[0]) read record [k].
The output field CTL_out[0] holds the number [k] of the currently
fetched record.
DESCRIPTION:
The created unit reads records from file pcFileName according to the
format specification in pcFmt. Records are separated by the newline
character. Each record can consist of a number of items or fields.
The format string specifies which fields shall be read from
each record, and which fields shall be ignored or skipped.
This is indicated by a number of control tokens of the form %c, where
c is a letter that indicates the type of the field (vector, image
or string) and/or the type of desired action (i.e., read or skip).
Additional numbers between the % and the c may give
additional specification about, e.g., the size of the field.
Currently, the recognized control tokens include:
- %df
- read first d elements of vector item [normal output field]
- %dF
- read first d elements of vector [packed output field]
- %dV
- read first d elements vector with dimension prefix [packed output field]
- %dv
- read first d elements vector with dimension prefix [normal output field]
- %x:yM
- read Mono image of size x * y (expected file entry
is file name of pgm - file)
- %x:yC
- read color image of size x * y [3 packed output fields]
(expected file entry
is file name of ppm - file)
- %iS
- skip i data fields in current record
- %n
- skip to next record
- %ir
- after the i-th record (or a higher record in the
case of random
access or index stride > 1) in the file was read,
continue with record 0.
If i is not specified, continue with record 0 when
end of file is encountered.
Control fields are matched in the order of their appearance in pcFmt
to fields in the current record of file fp.
For each specified item that is to be read, the unit will have one
(three in the case of a item that is a color image) output field(s)
at which the data of the associated data item that was read with
the last exec-call is available. The output field will be
packed, if the control token ends with a capital letter,
normal otherwise. The dimension of the output field will be given
by the dimension of the corresponding data item.
CONTROL MODES:
NST_F_CLOSE: close current file
NST_F_OPEN: re-open the file (implicitly done by each exec)
NST_RESET: reset unit so that next exec behaves as if
unit was freshly created
(the RESET itself does not fetch any new record)
EXAMPLES:
The format %5V%10v%80:80M%n will read the first two vectors
(of dimensions 5 and 10) and a following
mono-image of size 80x80 per record. All other items in the record are ignored.
The dimensions of the created output fields will be determined from the
first record in the accessed file. All further records are then assumed
to have the same structure (at least for their first three items).
STATUS:
Preliminary.
SEE ALSO:
write_data
FILE
/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/nst_file.c