NAME
read_image_dyn -- create unit to read data to file(s)
PROTOTYPE
unitptr read_image_dyn( 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 read.
A value of -1 indicates that not yet any record
has been read since the unit was created.
EXECUTION OF CREATED UNIT:
INITIALIZATION:
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 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:
- %M write Mono image of dynamic size
- %C write color image of dynamic size [3 packed output fields]
- %n write record separator
For each control field, the unit will have an input field (three
for the %C 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 read from the file pcFileName. Instead,
for each %M or %C control token, the associated image data are
written as a sequence of separate files with a common path, base name
and suffix, but a monotonically increasing additional number index.
Image dimensions are read from an input field.
The path, basename and suffix for each sequence are read from the
header part of the data file, the images themselves then appear
in the records of this file only by their number index. The companion
routine write_data_dyn can write this format by this referencing mechanism.
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 /mypath/myimage.pgm %M%n will read
records that consist of one dynamically-sized image.
The image data for the #-th record will be in file /mypath/myimage#.pgm.
The #-th record itself will just consist of
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_64//../foldersrc/nst_file.c