NAME
read_file - create unit for data input from file
PROTOTYPE
unitptr read_file( int n, char *pcFileId, char *pcFmt1, char *pcFmt2, int nr, unitptr dest)
ARGUMENTS
- int n
- number of data items returned by output vector of unit created
- char *pcFileId
- name of file to be read (convention as for fopen().
- char *pcFmt1
- format string for header (cf. below)
- char *pcFmt2
- format string for body (cf. below)
- int nr
- nr of records
- unitptr dest
- host unit
RETURN VALUE:
- unitptr u
- ptr to created instance
INTERFACE OF CREATED UNIT:
- X_in[2]:
- (input field 0) field to control read-
ing of next record if nr<0.
- X_out[n]:
- (output field 0) values read from file
- Y_out[2]:
- (output field 1) field whose second pin
provides the number of last record read
(the first pin is not used)
DESCRIPTION:
Creates a unit for carrying out file-I/O with file fileid.
The host unit of the newly created unit will be dest.
A call of read_file opens file fileid, moves the file
pointer beyond all tokens that are specified in format
string fmt1 and reads the first record as specified by for-
mat string fmt2. Each subsequent exec_unit -call reads
another record, always using the format fmt2 (NOTE: the
order in which records are fetched by the creation call and
the successive exec_unit-calls depends on the parameter nr
and on the values set at the control input field CTL_in, see
below).
The values obtained from the most recent read operation are
available on output field 0. Output field 1 provides the
record number (starting with 0 for the first record) of the
last record read.
The effect of a exec-call depends on the value of nr:
If nr=0, the creation call fetches the first record
immediately behind the items specified with fmt1, and
each exec call fetches the successor of the
current record. If EOF is reached,
the reading continues at the position of the first record
fetched (i.e. reading proceeds cyclically, but always skipping
the first part of the file as specified in fmt1).
If nr>0, either nr or all available records
(whichever number is smaller)
are read (again according to fmt2) into a buffer. Both
the creation call and each subsequent exec-call then returns
an element from this buffer. The returned element is
selected with input field X_in: if X_in[0]=0, the element
is chosen randomly; if X_in[0]!=0, the value X_in[1]
is used as the index of the returned element.
If nr<0, either ABS(nr) or all available records (which-
ever is smaller) are read into a buffer.
Access to these records can then
be controlled by input field X_in. If X_in[0]==0 (this is
the default) elements are fetched in sequential order.
I.e., the creation call fetches the first element in the buffer,
and each subsequent exec_unit call returns the successor of
the current record. If the last element in the
buffer has been fetched, the sequence continues with the
first element.
If the input pin X_in[0]!=0 the second pin X_in[1] is
taken to specify the number of the record that will be read
next (values X_[1]=0,1,2,.. specifying the first, the
second, the third etc. record).
In both cases, when nr!=0, the file is immediately closed,
when the data have been read into the buffer.
CONTROL MODES:
If nr=0, the file may be closed by a call
ctrl_unit(NST_I_CLOSE,u). Subsequent calls of exec_unit
will then be without effect. A call ctrl_unit(NST_I_OPEN,
u) re-opens the file, and moves the file pointer from the
beginning of the file beyond all items specified in format
string fmt1 (the call is without effect, if the file has not
been closed with NST_I_CLOSE before). As a result, the sub-
sequent behavior of the exec_unit-routine will be as if the
unit u had just been created. The combined effects of
NST_I_CLOSE and NST_I_OPEN can be obtained by a single call
of ctrl_unit(NST_RESET,u). In addition, this call also
resets sequential buffered access mode (i.e. nr<0 to the
first item in the buffer. All three calls are without any
effect, if nr>0.
FORMAT SPECIFICATION:
Each of the two format strings fmt1,fmt2 is of the form
fmt = "field_1 field_2 .."
The fields field_i are delimited by one or more blanks.
Each field_i is either a text token or a control field.
A text token is simply a consecutive string of charac-
ters (delimited by blanks) that must not begin with a single
percent char %.
A text token advances the file pointer
immediately behind the next occurrence of the same text
token in the file, or to EOF, if there is no further occurrence.
A control field is any field beginning with a single %
(such as %34.5) and delimited by blanks. The following
kinds of control fields are recognized (.d1 and d2 denote non-
negative integers without sign):
- d1-d2
- assign the next d2-d1+1 float values
in the file to outputs X_out[d1]..X_out[d2].
- d1
- assign next float value in the file to
X_out[d1].
- sd1
- skip next d1 tokens (text or numbers)
in the file.
- n
- skip rest of current line.
- d1.d2
- use format d1.d2f for remaining writes
(may occur, but will be ignored by this
routine)
If a token that is expected to represent a float value is
instead a text token, a value of 0 is read.
DIAGNOSTICS:
If the file has not been found or EOF is reached during
reading an error message is issued. In this case, the
returned pointer will be NULL.
EXAMPLES OF FORMAT SPECIFICATION:
- "s5 0-10 n 11-20"
- skip first 5 tokens, assign next
eleven tokens to X_out[0..10],
skip to next line and
assign first 10 tokens
to X_out[11..20].
- "eps 3 sigma1,sigma2 1-2 n s4 0"
-
Assign to X_out[3] first
float item after token eps,
to X_out[1], X_out[2]
the two numbers following the next
occurrence of sigma1,
sigma2, and assign the 5th
token on the next line
to X_out[0].
EXAMPLES:
The program fview.c provides an example of the use of the
read_file-unit.
SEE ALSO:
write_file, write_data
FILE
/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/nst_file.c