NAME
write_file - create unit for writing data to file
PROTOTYPE
unitptr write_file( int n, char *pcFileid, char *pcFmt1, char *pcFmt2, unitptr dest)
ARGUMENTS
- int n
- dimensionality of input vector
- char *pcFileid
- name of file to be written
- char *pcFmt1
- format string for file header
- char *pcFmt2
- format string for file body, specifies writing of data elements from input vector to file fileid.
- unitptr dest
- host unit
RETURN VALUE:
- unitptr u
- pointer to created instance
INTERFACE OF CREATED UNIT:
- X[n]:
- (input field 0) input vector whose
values are written
DESCRIPTION:
A call of write_file opens file fileid and creates a unit
for carrying out file-I/O with the opened file. The host
unit of the newly created unit will be dest.
The first subsequent call of exec_unit then writes a
header part according to format specification pcFmt1,
followed by successive write's according to pcFmt2.
Each such subsequent call of exec_unit
results in a write only according to pcFmt2 alone.
CONTROL MODES:
A call ctrl_unit(NST_I_CLOSE, u) closes the file associated
with u. Subsequent calls of exec_unit will then be without
effect. A call ctrl_unit(NST_I_OPEN, u) re-opens the file
and sets the file pointer to the beginning of the file. As
a result, the former content of the file is lost, and the
behavior of the exec_unit -routine will be as if the unit u
had been just been created. In particular, the first call of
the exec_unit -routine will include writing of the header
specified in pcFmt1. Rewriting the header without moving to
the beginning of the file is possible by a call
ctrl_unit(NST_RESET,u). This allows to insert arbitrary
messages into the file by suitably changing the contents of the
memory locations referenced by pcFmt1.
FORMAT SPECIFICATION:
A valid format specification is of the form
pcFmt = "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 characters
(delimited by blanks) that must not begin with a single
%. A text token is simply written to the file.
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
- write values X_in[d1]..X_in[d2] of
input pins of field X_in to file.
- d1
- write value at input pin d1 to the file.
- sd1
- allowed, but ignored in this routine.
- n
- write newline-character to file.
- d1.d2
- use format d1.d2f for remaining writes
(default format is 8.3f).
If pcFmt1 contains the token "%TRAILER:%", the part before
the token is used as header, and the part behind the
token as trailer written before the file is closed.
EXAMPLE OF FORMAT SPECIFICATION:
- "s5 0-10 n 12.4 11-20"
-
writes values at pins 0...10, proceeds
to next line, changes format to 12.4f and
writes elements 11..20 in the new format.
FILE:
nst_file
SEE ALSO:
read_file, write_data, printf_unit
FILE
/homes/jontrup/nst5/man/../o.sol2//../foldersrc/nst_file.c