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_64//../foldersrc/nst_file.c