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