NAME
write_data -- create unit to write data to file(s)
PROTOTYPE
unitptr write_data( char *pcFileName, char *pcFmtStr, char *pcHeader, unitptr uHost)
ARGUMENTS
- char *pcFileName
- file name for output file. Specify a trailing '+'-mark (separated by a blank from the file name) to append data to an existing file.
- char *pcFmtStr
- format string
- char *pcHeader
- header to be prepended
- unitptr uHost
- host unit
RETURN VALUE:
A pointer to the created unit or NULL in the case of an error.
INTERFACE OF CREATED UNIT:
- in_0..n-1:
- nr and type of input fields depends on specifications
in format string pcFmtStr (see below).
- CTL_in[1]:
- (control field)
- X_out[1]:
- (output field 0) nr of last record written.
A value of -1 indicates that not yet any record
has been written since the unit was created.
EXECUTION OF CREATED UNIT:
INITIALIZATION:
DESCRIPTION:
The created unit writes records to 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 written as
one record.
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).
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 write vector item of dimension d [normal input field]
- %dF write vector item of dimension d [packed input field]
- %dV write vector with dimension prefix [packed output field]
- %dv write vector with dimension prefix [normal output field]
- %x:yM write Mono image of size x*y
- %M Creates a single input field with one pin.
This variant without arguments x:y is provided to
suppress the writing of the image data in case that these
data are already available in a file /path/basename#.pgm. In
this case, the index # of this file should be given at the single
pin of the input field that was created by the %M format field.
The /path/basename and pgm - part must be specified in front of
the format field (cf. below).
- %x:yC write color image of size x*y [3 packed output fields]
- %C analogous to %M-format field, but for .ppm-file.
- %n write record separator
For each control field, the unit will have an input field (three
for the %x:yC control field) at which the data values to be written
must be provided.
The input field will be
packed, if the control token ends with a capital letter, or if a
negative vector dimension was specified,
normal otherwise.
NOTE:
Image data are not directly written into the file pcFileName. Instead,
for each %x:yM or %x:yC control token, the associated image data are
written as a sequence of separate files with a common path, base name
and suffix, but a monotonously increasing additional number index.
For each %M or %C control token, the specification of the path,
basename and file suffix is simply made by writing this information
in front of the control token (any spaces or superfluous characters
are ignored).
The path, basename and suffix for each sequence are written into the
header part of the created data file, the images themselves then appear
in the records of this file only by their number index. The compagnon
routine read_data can read this format and access the image data
by this referencing mechanism.
The writing of the image data can be suppressed by omitting the
size specification x:y. In this case, the created unit will have
a single unpacked input field with one pin for the index of an
filename of an already existing file containing the image data.
In this case, the writing of a new file will be suppressed, and
the provided index (together with the path and basename specified
before the format field) will be used to embed suitable referencing
information in the written file.
CONTROL MODES:
NST_I_CLOSE: close current file
NST_RESET:
NST_I_OPEN: append, if file exists, otherwise create new
and prepend header.
EXAMPLES:
The format %-10v%10v /mypath/myimage.pgm %80:80M%n will write
records that consist of two 10-dimensional vectors and one 80x80-image.
The image data for the #-th record will be in file /mypath/myimage#.pgm.
The #-th record itself will just consist of two vectors, followed
by the integer +#. The file path /mypath, the basename myimage
and the type suffix .pgm will be written into the file header.
STATUS:
Preliminary.
SEE ALSO:
write_file, read_data
FILE
/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/nst_file.c